README.md
1# libnetwork - networking for containers
2
3[](https://circleci.com/gh/docker/libnetwork/tree/master) [](https://coveralls.io/r/docker/libnetwork) [](https://godoc.org/github.com/docker/libnetwork) [](https://goreportcard.com/report/github.com/docker/libnetwork)
4
5Libnetwork provides a native Go implementation for connecting containers
6
7The goal of libnetwork is to deliver a robust Container Network Model that provides a consistent programming interface and the required network abstractions for applications.
8
9#### Design
10Please refer to the [design](docs/design.md) for more information.
11
12#### Using libnetwork
13
14There are many networking solutions available to suit a broad range of use-cases. libnetwork uses a driver / plugin model to support all of these solutions while abstracting the complexity of the driver implementations by exposing a simple and consistent Network Model to users.
15
16
17```go
18func main() {
19 if reexec.Init() {
20 return
21 }
22
23 // Select and configure the network driver
24 networkType := "bridge"
25
26 // Create a new controller instance
27 driverOptions := options.Generic{}
28 genericOption := make(map[string]interface{})
29 genericOption[netlabel.GenericData] = driverOptions
30 controller, err := libnetwork.New(config.OptionDriverConfig(networkType, genericOption))
31 if err != nil {
32 log.Fatalf("libnetwork.New: %s", err)
33 }
34
35 // Create a network for containers to join.
36 // NewNetwork accepts Variadic optional arguments that libnetwork and Drivers can use.
37 network, err := controller.NewNetwork(networkType, "network1", "")
38 if err != nil {
39 log.Fatalf("controller.NewNetwork: %s", err)
40 }
41
42 // For each new container: allocate IP and interfaces. The returned network
43 // settings will be used for container infos (inspect and such), as well as
44 // iptables rules for port publishing. This info is contained or accessible
45 // from the returned endpoint.
46 ep, err := network.CreateEndpoint("Endpoint1")
47 if err != nil {
48 log.Fatalf("network.CreateEndpoint: %s", err)
49 }
50
51 // Create the sandbox for the container.
52 // NewSandbox accepts Variadic optional arguments which libnetwork can use.
53 sbx, err := controller.NewSandbox("container1",
54 libnetwork.OptionHostname("test"),
55 libnetwork.OptionDomainname("docker.io"))
56 if err != nil {
57 log.Fatalf("controller.NewSandbox: %s", err)
58 }
59
60 // A sandbox can join the endpoint via the join api.
61 err = ep.Join(sbx)
62 if err != nil {
63 log.Fatalf("ep.Join: %s", err)
64 }
65
66 // libnetwork client can check the endpoint's operational data via the Info() API
67 epInfo, err := ep.DriverInfo()
68 if err != nil {
69 log.Fatalf("ep.DriverInfo: %s", err)
70 }
71
72 macAddress, ok := epInfo[netlabel.MacAddress]
73 if !ok {
74 log.Fatalf("failed to get mac address from endpoint info")
75 }
76
77 fmt.Printf("Joined endpoint %s (%s) to sandbox %s (%s)\n", ep.Name(), macAddress, sbx.ContainerID(), sbx.Key())
78}
79```
80
81## Future
82Please refer to [roadmap](ROADMAP.md) for more information.
83
84## Contributing
85
86Want to hack on libnetwork? [Docker's contributions guidelines](https://github.com/docker/docker/blob/master/CONTRIBUTING.md) apply.
87
88## Copyright and license
89Code and documentation copyright 2015 Docker, inc. Code released under the Apache 2.0 license. Docs released under Creative commons.
90
){kind=link}
){kind=link}
){kind=link}