this repo has no description
anil.recoil.org
1opam-version: "2.0"
2maintainer: "Magnus Skjegstad <magnus@skjegstad.com>"
3authors: "Magnus Skjegstad <magnus@skjegstad.com>"
4homepage: "https://github.com/mirage/mirage-vnetif"
5bug-reports: "https://github.com/mirage/mirage-vnetif/issues/"
6dev-repo: "git+https://github.com/mirage/mirage-vnetif.git"
7doc: "https://docs.mirage.io/mirage-vnetif"
8license: "ISC"
9
10build: [
11 ["jbuilder" "subst" "-p" name] {dev}
12 ["jbuilder" "build" "-p" name "-j" jobs]
13]
14
15depends: [
16 "ocaml" {>= "4.04.2"}
17 "jbuilder" {>= "1.0+beta7"}
18 "lwt"
19 "mirage-time-lwt" {>= "1.0.0"}
20 "mirage-clock-lwt" {>= "1.2.0"}
21 "mirage-net-lwt" {>= "1.0.0" & < "2.0.0"}
22 "cstruct" {>= "2.4.0" & < "6.1.0"}
23 "ipaddr" {>= "3.0.0"}
24 "macaddr"
25 "io-page"
26 "mirage-profile"
27 "duration"
28 "logs"
29 "result"
30]
31tags: ["org:mirage"]
32synopsis: "Virtual network interface and software switch for Mirage"
33description: """\
34
35Provides the module `Vnetif` which can be used as a replacement for the regular `Netif` implementation in Xen and Unix. Stacks built using `Vnetif` are connected to a software switch that allows the stacks to communicate as if they were connected to the same LAN.
36
37An example of a unikernel that communicates with itself over `Vnetif` can be seen [here](https://github.com/MagnusS/mirage-vnetif/blob/master/examples/connect/unikernel.ml). An iperf-like performance test is available [here](https://github.com/MagnusS/mirage-vnetif/tree/master/examples/iperf_self). The examples can be compiled for Unix and Xen and do not need access to a real network interface.
38
39## Install
40
41```
42opam install mirage-vnetif
43```
44
45## Getting started
46
47First, construct a TCP/IP stack based on `vnetif`:
48
49```ocaml
50 module S = struct
51 module B = Basic_backend.Make
52 module V = Vnetif.Make(B)
53 module E = Ethif.Make(V)
54 module I = Ipv4.Make(E)(Clock)(OS.Time)
55 module U = Udp.Make(I)
56 module T = Tcp.Flow.Make(I)(OS.Time)(Clock)(Random)
57 module S = Tcpip_stack_direct.Make(C)(OS.Time)(Random)(V)(E)(I)(U)(T)
58 include S
59 end
60```
61
62Since we don't have the mirage-tool to help us we have to construct the stack manually. This code would usually be generated in `main.ml` by `mirage configure --xen/unix`.
63
64```ocaml
65let or_error name fn t =
66 fn t
67 >>= function
68 | `Error e -> fail (Failure ("Error starting " ^ name))
69 | `Ok t -> return t
70
71let create_stack c backend ip netmask gw =
72 or_error "backend" S.V.connect backend >>= fun netif ->
73 or_error "ethif" S.E.connect netif >>= fun ethif ->
74 or_error "ipv4" S.I.connect ethif >>= fun ipv4 ->
75 or_error "udpv4" S.U.connect ipv4 >>= fun udpv4 ->
76 or_error "tcpv4" S.T.connect ipv4 >>= fun tcpv4 ->
77 let config = {
78 Mirage_types_lwt.name = "stack";
79 Mirage_types_lwt.console = c;
80 Mirage_types_lwt.interface = netif;
81 Mirage_types_lwt.mode = `IPv4 (ip, netmask, gw);
82 } in
83 or_error "stack" (S.connect config ethif ipv4 udpv4) tcpv4
84
85```
86
87
88We can now create multiple stacks that talk over the same backend. `Basic_backend.create` accepts two optional parameters:
89- `use_async_readers` makes the `write` calls non-blocking. This is necessary to use Vnetif with the Mirage TCP/IP stack.
90- `yield` specifies the yield function to use in non-blocking mode. In a unikernel this is typically `OS.Time.sleep 0.0`, but in a Unix process `Lwt_main.yield ()` can be used instead.
91
92```ocaml
93
94let () =
95
96 (* create async backend with OS.Time.sleep 0.0 as yield *)
97 let backend = Basic_backend.create ~use_async_readers:true
98 ~yield:(fun() -> OS.Time.sleep 0.0 ) () in
99
100 let netmask = Ipaddr.V4.of_string_exn "255.255.255.0" in
101 let gw = Ipaddr.V4.of_string_exn "10.0.0.1" in
102
103 let server_ip = Ipaddr.V4.of_string_exn "10.0.0.100" in
104 create_stack c backend server_ip netmask [gw] >>= fun server_stack ->
105
106 let client_ip = Ipaddr.V4.of_string_exn "10.0.0.101" in
107 create_stack c backend server_ip netmask [gw] >>= fun client_stack ->
108```
109
110The stacks can now be used as regular Mirage TCP/IP stacks, e.g.:
111
112```ocaml
113S.listen_tcpv4 server_stack ~port:80 (fun f -> ...);
114S.listen s1
115```
116
117## Build examples
118```
119mirage configure --xen/--unix
120make
121```"""
122url {
123 src:
124 "https://github.com/mirage/mirage-vnetif/releases/download/v0.4.1/mirage-vnetif-0.4.1.tbz"
125 checksum: [
126 "sha256=9049f14348e26838dde7906c23763d0ea415937895c2510811ae62c76e9e6301"
127 "md5=5b8e5c8fd0b1eb93d5296b03d62eb0b7"
128 ]
129}