module Key : module type of struct include Mirage_key end
Configuration keys.
include Functoria_app.DSL
Combinators
The type for values representing module types.
val typ : 'a -> 'a typ
type t
is a value representing the module type t
.
Construct a functor type from a type and an existing functor type. This corresponds to prepending a parameter to the list of functor parameters. For example:
kv_ro @-> ip @-> kv_ro
This describes a functor type that accepts two arguments -- a kv_ro
and an ip
device -- and returns a kv_ro
.
type job = Functoria.job
Type for job values.
type 'a impl = 'a Functoria.impl
The type for values representing module implementations.
The type for abstract implementations.
val abstract : _ impl -> abstract_impl
abstract t
is t
but with its type variable abstracted. Useful for dependencies.
Keys
type key = Functoria_key.t
The type for command-line keys. See Functoria_key.t
.
type context = Functoria_key.context
The type for keys' parsing context. See Functoria_key.context
.
type 'a value = 'a Functoria_key.value
The type for values parsed from the command-line. See Functoria_key.value
.
if_impl v impl1 impl2
is impl1
if v
is resolved to true and impl2
otherwise.
match_impl v cases ~default
chooses the implementation amongst cases
by matching the v
's value. default
is chosen if no value matches.
module type KEY = module type of Functoria_key with type 'a Arg.converter = 'a Functoria_key.Arg.converter and type 'a Arg.t = 'a Functoria_key.Arg.t and type Arg.info = Functoria_key.Arg.info and type 'a value = 'a Functoria_key.value and type 'a key = 'a Functoria_key.key and type t = Functoria_key.t and type Set.t = Functoria_key.Set.t and type 'a Alias.t = 'a Functoria_key.Alias.t and type context = Functoria_key.context
The signature for run-time and configure-time command-line keys.
Package dependencies
type package = private Functoria.package = {
opam : string; |
pin : string option; |
build : bool; |
ocamlfind : Astring.String.Set.t; |
min : Astring.String.Set.t; |
max : Astring.String.Set.t; |
}
The type of a package
val package : ?build:bool -> ?sublibs:string list -> ?ocamlfind:string list -> ?min:string -> ?max:string -> ?pin:string -> string -> package
package ~build ~sublibs ~ocamlfind ~min ~max ~pin opam
is a package
. Build
indicates a build-time dependency only, defaults to false
. The ocamlfind name is by default the same as opam
, you can specify ~sublibs
to add additional sublibraries (e.g. ~sublibs:["mirage"] "foo"
will result in the findlib names ["foo"; "foo.mirage"]
. In case the findlib name is disjoint (or empty), use ~ocamlfind
. Specifying both ~ocamlfind
and ~sublibs
leads to an invalid argument. Version constraints are given as min
(inclusive) and max
(exclusive). If pin
is provided, a pin-depends is generated.
Application Builder
val foreign : ?packages:package list -> ?keys:key list -> ?deps:abstract_impl list -> string -> 'a typ -> 'a impl
foreign name typ
is the module name
, having the module type typ
.
- If
packages
is set, then the given packages are installed before compiling the current application. - If
keys
is set, use the given keys to parse at configure and runtime the command-line arguments before callingname.connect
. - If
deps
is set, the given list of abstract implementations is added as data-dependencies: they will be initialized before callingname.connect
.
For a more flexible definition of packages, or for a custom configuration step, see the configurable
class type and the foreign
class.
module Info = Functoria.Info
Information about the final application.
class type 'ty configurableobject ... end
Signature for configurable module implementations. A configurable
is a module implementation which contains a runtime state which can be set either at configuration time (by the application builder) or at runtime, using command-line arguments.
val impl : 'a configurable -> 'a impl
impl c
is the implementation of the configurable c
.
class base_configurable : object ... end
base_configurable
pre-defining many methods from the configurable
class. To be used as follow:
class 'a foreign : ?packages:package list -> ?keys:key list -> ?deps:abstract_impl list -> string -> 'a typ -> 'a configurable
This class can be inherited to define a configurable
with an API similar to foreign
.
Sharing
val hash : 'a impl -> int
hash
is the hash function on implementations. FIXME(samoht) expand on how it works.
module ImplTbl = Functoria.ImplTbl
Hashtbl of implementations.
General mirage devices
Use mirage-profile to trace the unikernel. On Unix, this creates and mmaps a file called "trace.ctf". On Xen, it shares the trace buffer with dom0.
- parameter size:
size of the ring buffer to use.
For the Qubes target, the Qubes database from which to look up * dynamic runtime configuration information.
A default qubes database, guessed from the usual valid configurations.
Time
Clocks
Log reporters
val default_reporter : ?clock:pclock impl -> ?ring_size:int -> ?level:Logs.level -> unit -> reporter impl
default_reporter ?clock ?level ()
is the log reporter that prints log messages to the console, timestampted with clock
. If not provided, the default clock is default_posix_clock
. level
is the default log threshold. It is Logs.Info
if not specified.
Random
Default PRNG device to be used in unikernels. It uses getrandom/getentropy on Unix, and a Fortuna PRNG on other targets.
Consoles
Block devices
Use the given XenStore ID (ex: /dev/xvdi1
or 51760
) as a raw block device.
val generic_block : ?group:string -> ?key:[ `XenstoreId | `BlockFile | `Ramdisk ] value -> string -> block impl
Static key/value stores
Direct access to the underlying filesystem as a key/value store. For Xen backends, this is equivalent to crunch
.
val generic_kv_ro : ?group:string -> ?key:[ `Archive | `Crunch | `Direct | `Fat ] value -> string -> kv_ro impl
Generic key/value that will choose dynamically between fat
, archive
and crunch
. To use a filesystem implementation, try kv_ro_of_fs
.
If no key is provided, it uses Key.kv_ro
to create a new one.
Direct access to the underlying filesystem as a key/value store. Only available on Unix backends.
An in-memory key-value store using mirage-kv-mem
.
Filesystem
fat_files dir ?dir ?regexp ()
collects all the files matching the shell pattern regexp
in the directory dir
into a FAT image. By default, dir
is the current working directory and regexp
is *
Consider a filesystem implementation as a read-only key/value store.
Network interfaces
default_network
is a dynamic network implementation * which attempts to do something reasonable based on the target.
A custom network interface. Exposes a Key.interface
key.
Ethernet configuration
ARP configuration
ARP implementation provided by the arp library
IP configuration
Types for IPv4 manual configuration.
type ipv6_config = {
addresses : Ipaddr.V6.t list; |
netmasks : Ipaddr.V6.Prefix.t list; |
gateways : Ipaddr.V6.t list; |
}
Types for IP manual configuration.
val create_ipv4 : ?group:string -> ?config:ipv4_config -> ?random:random impl -> ?clock:mclock impl -> ethernet impl -> arpv4 impl -> ipv4 impl
Use an IPv4 address Exposes the keys Key.V4.network
and Key.V4.gateway
. If provided, the values of these keys will override those supplied in the ipv4 configuration record, if that has been provided.
val ipv4_qubes : ?random:random impl -> ?clock:mclock impl -> qubesdb impl -> ethernet impl -> arpv4 impl -> ipv4 impl
Use a given initialized QubesDB to look up and configure the appropriate * IPv4 interface.
val create_ipv6 : ?random:random impl -> ?time:time impl -> ?clock:mclock impl -> ?group:string -> ethernet impl -> ipv6_config -> ipv6 impl
Use an IPv6 address. Exposes the keys Key.V6.ips
, Key.V6.netmasks
and Key.V6.gateways
.
UDP configuration
val socket_udpv4 : ?group:string -> Ipaddr.V4.t option -> udpv4 impl
TCP configuration
val direct_tcp : ?clock:mclock impl -> ?random:random impl -> ?time:time impl -> 'a ip impl -> 'a tcp impl
val socket_tcpv4 : ?group:string -> Ipaddr.V4.t option -> tcpv4 impl
Network stack configuration
val direct_stackv4 : ?clock:mclock impl -> ?random:random impl -> ?time:time impl -> ?group:string -> network impl -> ethernet impl -> arpv4 impl -> ipv4 impl -> stackv4 impl
Direct network stack with given ip.
val socket_stackv4 : ?group:string -> Ipaddr.V4.t list -> stackv4 impl
Network stack with sockets. Exposes the key Key
.V4.interfaces.
val qubes_ipv4_stack : ?group:string -> ?qubesdb:qubesdb impl -> ?arp:(ethernet impl -> arpv4 impl) -> network impl -> stackv4 impl
Build a stackv4 by looking up configuration information via QubesDB, * building an ipv4, then building a stack on top of that.
val dhcp_ipv4_stack : ?group:string -> ?random:random impl -> ?time:time impl -> ?arp:(ethernet impl -> arpv4 impl) -> network impl -> stackv4 impl
Build a stackv4 by obtaining a DHCP lease, using the lease to * build an ipv4, then building a stack on top of that.
val static_ipv4_stack : ?group:string -> ?config:ipv4_config -> ?arp:(ethernet impl -> arpv4 impl) -> network impl -> stackv4 impl
Build a stackv4 by checking the Key.V4.network
, and Key.V4.gateway
keys * for ipv4 configuration information, filling in unspecified information from ?config
, * then building a stack on top of that.
val generic_stackv4 : ?group:string -> ?config:ipv4_config -> ?dhcp_key:bool value -> ?net_key:[ `Direct | `Socket ] option value -> network impl -> stackv4 impl
Generic stack using a dhcp
and a net
keys: Key.net
and Key.dhcp
.
- If
target
=Qubes
thenqubes_ipv4_stack
is used - Else, if
net
=socket
thensocket_stackv4
is used - Else, if
dhcp
thendhcp_ipv4_stack
is used - Else, if
unix or macosx
thensocket_stackv4
is used - Else,
static_ipv4_stack
is used.
If a key is not provided, it uses Key.net
or Key.dhcp
(with the group
argument) to create it.
Resolver configuration
val resolver_dns : ?ns:Ipaddr.V4.t -> ?ns_port:int -> ?random:random impl -> ?time:time impl -> ?mclock:mclock impl -> stackv4 impl -> resolver impl
Syslog configuration
type syslog_config = {
hostname : string; |
server : Ipaddr.V4.t option; |
port : int option; |
truncate : int option; |
}
val syslog_config : ?port:int -> ?truncate:int -> ?server:Ipaddr.V4.t -> string -> syslog_config
Helper for constructing a syslog_config
.
val syslog_udp : ?config:syslog_config -> ?console:console impl -> ?clock:pclock impl -> stackv4 impl -> syslog impl
Emit log messages via UDP to the configured host.
val syslog_tcp : ?config:syslog_config -> ?console:console impl -> ?clock:pclock impl -> stackv4 impl -> syslog impl
Emit log messages via TCP to the configured host.
val syslog_tls : ?config:syslog_config -> ?keyname:string -> ?console:console impl -> ?clock:pclock impl -> stackv4 impl -> kv_ro impl -> syslog impl
Emit log messages via TLS to the configured host, using the credentials (private ekey, certificate, trust anchor) provided in the KV_RO using the keyname
.
Entropy
Conduit configuration
HTTP configuration
Argv configuration
val default_argv : Functoria_app.argv impl
default_argv
is a dynamic argv implementation * which attempts to do something reasonable based on the target.
val no_argv : Functoria_app.argv impl
no_argv
Disable command line parsing and set argv to |""|
.
Other devices
app_info
exports all the information available at configure time into a runtime Mirage.Info.t
value.
Application registering
val register : ?argv:Functoria_app.argv impl -> ?tracing:tracing impl -> ?reporter:reporter impl -> ?keys:Key.t list -> ?packages:Functoria.package list -> string -> job impl list -> unit
register name jobs
registers the application named by name
which will executes the given jobs
.
- parameter packages
The opam packages needed by this module.
- parameter keys
The keys related to this module.
- parameter tracing
Enable tracing.
- parameter reporter
Configure logging. The default log reporter is
default_reporter
. To disable logging, useno_reporter
.
- parameter argv
Configure command-line argument parsing. The default parser is
default_argv
. To disable command-line parsing, useno_argv
.