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"
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 "io-page"
25 "mirage-profile"
26 "duration"
27 "result"
28 "logs"
29]
30tags: ["org:mirage"]
31synopsis: "Virtual network interface and software switch for Mirage"
32description: """
33Provides 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.
34
35An 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.
36
37## Install
38
39```
40opam install mirage-vnetif
41```
42
43## Getting started
44
45First, construct a TCP/IP stack based on `vnetif`:
46
47```ocaml
48 module S = struct
49 module B = Basic_backend.Make
50 module V = Vnetif.Make(B)
51 module E = Ethif.Make(V)
52 module I = Ipv4.Make(E)(Clock)(OS.Time)
53 module U = Udp.Make(I)
54 module T = Tcp.Flow.Make(I)(OS.Time)(Clock)(Random)
55 module S = Tcpip_stack_direct.Make(C)(OS.Time)(Random)(V)(E)(I)(U)(T)
56 include S
57 end
58```
59
60Since 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`.
61
62```ocaml
63let or_error name fn t =
64 fn t
65 >>= function
66 | `Error e -> fail (Failure ("Error starting " ^ name))
67 | `Ok t -> return t
68
69let create_stack c backend ip netmask gw =
70 or_error "backend" S.V.connect backend >>= fun netif ->
71 or_error "ethif" S.E.connect netif >>= fun ethif ->
72 or_error "ipv4" S.I.connect ethif >>= fun ipv4 ->
73 or_error "udpv4" S.U.connect ipv4 >>= fun udpv4 ->
74 or_error "tcpv4" S.T.connect ipv4 >>= fun tcpv4 ->
75 let config = {
76 Mirage_types_lwt.name = "stack";
77 Mirage_types_lwt.console = c;
78 Mirage_types_lwt.interface = netif;
79 Mirage_types_lwt.mode = `IPv4 (ip, netmask, gw);
80 } in
81 or_error "stack" (S.connect config ethif ipv4 udpv4) tcpv4
82
83```
84
85
86We can now create multiple stacks that talk over the same backend. `Basic_backend.create` accepts two optional parameters:
87- `use_async_readers` makes the `write` calls non-blocking. This is necessary to use Vnetif with the Mirage TCP/IP stack.
88- `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.
89
90```ocaml
91
92let () =
93
94 (* create async backend with OS.Time.sleep 0.0 as yield *)
95 let backend = Basic_backend.create ~use_async_readers:true
96 ~yield:(fun() -> OS.Time.sleep 0.0 ) () in
97
98 let netmask = Ipaddr.V4.of_string_exn "255.255.255.0" in
99 let gw = Ipaddr.V4.of_string_exn "10.0.0.1" in
100
101 let server_ip = Ipaddr.V4.of_string_exn "10.0.0.100" in
102 create_stack c backend server_ip netmask [gw] >>= fun server_stack ->
103
104 let client_ip = Ipaddr.V4.of_string_exn "10.0.0.101" in
105 create_stack c backend server_ip netmask [gw] >>= fun client_stack ->
106```
107
108The stacks can now be used as regular Mirage TCP/IP stacks, e.g.:
109
110```ocaml
111S.listen_tcpv4 server_stack ~port:80 (fun f -> ...);
112S.listen s1
113```
114
115## Build examples
116```
117mirage configure --xen/--unix
118make
119```"""
120url {
121 src:
122 "https://github.com/mirage/mirage-vnetif/releases/download/v0.4.0/mirage-vnetif-0.4.0.tbz"
123 checksum: [
124 "sha256=052b5b2bf93d68c99f2021115611b46c6eccf78923cf5fd76fd7fa14ecb01837"
125 "md5=8ee3b8f3cd9069cd930ce52d78502592"
126 ]
127}