github.com/vishvananda/netlink@v1.3.0/README.md (about)

     1  # netlink - netlink library for go #
     2  
     3  ![Build Status](https://github.com/vishvananda/netlink/actions/workflows/main.yml/badge.svg) [![GoDoc](https://godoc.org/github.com/vishvananda/netlink?status.svg)](https://godoc.org/github.com/vishvananda/netlink)
     4  
     5  The netlink package provides a simple netlink library for go. Netlink
     6  is the interface a user-space program in linux uses to communicate with
     7  the kernel. It can be used to add and remove interfaces, set ip addresses
     8  and routes, and configure ipsec. Netlink communication requires elevated
     9  privileges, so in most cases this code needs to be run as root. Since
    10  low-level netlink messages are inscrutable at best, the library attempts
    11  to provide an api that is loosely modeled on the CLI provided by iproute2.
    12  Actions like `ip link add` will be accomplished via a similarly named
    13  function like AddLink(). This library began its life as a fork of the
    14  netlink functionality in
    15  [docker/libcontainer](https://github.com/docker/libcontainer) but was
    16  heavily rewritten to improve testability, performance, and to add new
    17  functionality like ipsec xfrm handling.
    18  
    19  ## Local Build and Test ##
    20  
    21  You can use go get command:
    22  
    23      go get github.com/vishvananda/netlink
    24  
    25  Testing dependencies:
    26  
    27      go get github.com/vishvananda/netns
    28  
    29  Testing (requires root):
    30  
    31      sudo -E go test github.com/vishvananda/netlink
    32  
    33  ## Examples ##
    34  
    35  Add a new bridge and add eth1 into it:
    36  
    37  ```go
    38  package main
    39  
    40  import (
    41      "fmt"
    42      "github.com/vishvananda/netlink"
    43  )
    44  
    45  func main() {
    46      la := netlink.NewLinkAttrs()
    47      la.Name = "foo"
    48      mybridge := &netlink.Bridge{LinkAttrs: la}
    49      err := netlink.LinkAdd(mybridge)
    50      if err != nil  {
    51          fmt.Printf("could not add %s: %v\n", la.Name, err)
    52      }
    53      eth1, _ := netlink.LinkByName("eth1")
    54      netlink.LinkSetMaster(eth1, mybridge)
    55  }
    56  
    57  ```
    58  Note `NewLinkAttrs` constructor, it sets default values in structure. For now
    59  it sets only `TxQLen` to `-1`, so kernel will set default by itself. If you're
    60  using simple initialization(`LinkAttrs{Name: "foo"}`) `TxQLen` will be set to
    61  `0` unless you specify it like `LinkAttrs{Name: "foo", TxQLen: 1000}`.
    62  
    63  Add a new ip address to loopback:
    64  
    65  ```go
    66  package main
    67  
    68  import (
    69      "github.com/vishvananda/netlink"
    70  )
    71  
    72  func main() {
    73      lo, _ := netlink.LinkByName("lo")
    74      addr, _ := netlink.ParseAddr("169.254.169.254/32")
    75      netlink.AddrAdd(lo, addr)
    76  }
    77  
    78  ```
    79  
    80  ## Future Work ##
    81  
    82  Many pieces of netlink are not yet fully supported in the high-level
    83  interface. Aspects of virtually all of the high-level objects don't exist.
    84  Many of the underlying primitives are there, so its a matter of putting
    85  the right fields into the high-level objects and making sure that they
    86  are serialized and deserialized correctly in the Add and List methods.
    87  
    88  There are also a few pieces of low level netlink functionality that still
    89  need to be implemented. Routing rules are not in place and some of the
    90  more advanced link types. Hopefully there is decent structure and testing
    91  in place to make these fairly straightforward to add.
    92