github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/plugins/drivers/community/jail-task-driver.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Drivers: jail-task-driver'
     4  description: >-
     5    The Jail task driver is used to run application containers using FreeBSD
     6    jails.
     7  ---
     8  
     9  # Jail task Driver
    10  
    11  Name: `jail-task-driver`
    12  
    13  The Jail task driver provides an interface for using FreeBSD jails for running application
    14  containers. You can download the external jail-task-driver [here][jail-task-driver]. For more detailed instructions on how to set up and use this driver, please refer to the [guide][jail-task-guide].
    15  
    16  ## Task Configuration
    17  
    18  ```hcl
    19  task "http-echo-jail" {
    20  		driver = "jail-task-driver"
    21  		config {
    22  			Path  = "/zroot/iocage/jails/myjail/root"
    23  			Allow_raw_sockets = true
    24  			Allow_chflags     = true
    25  			Ip4_addr          = "em1|192.168.1.102"
    26  			Exec_start        = "/usr/local/bin/http-echo -listen :9999 -text hello"
    27  			Rctl =  {
    28  				Vmemoryuse = {
    29  					Action = "deny"
    30  					Amount = "1G"
    31  					Per = "process"
    32  				}
    33  				Openfiles = {
    34  					Action = "deny"
    35  					Amount = "500"
    36  				}
    37  			}
    38  		}
    39  	}
    40  ```
    41  
    42  The Jail task driver supports most of [JAIL(8)][jail(8)] parameters, for a list of the currently supported parameters, please refer to the [Parameter Documentation][parameter-doc].
    43  
    44  - `Path` - (Optional) The directory which is to be the root of the jail.
    45    Defaults to the [allocation working directory].
    46  
    47  - `Ip4` - (Optional) Control the availability of IPv4 addresses. Possible values are
    48    **"inherit"** to allow unrestricted access to all system addresses,
    49    **"new"** to restrict addresses via Ip4_addr, and "**disable"** to stop
    50    the jail from using IPv4 entirely.
    51  
    52  ~> Note : Setting the Ip4_addr parameter implies a value of **"new"**
    53  
    54  - `Ip4_addr` - (Optional) A list of IPv4 addresses assigned to the jail. If this is set,
    55    the jail is restricted to using only these addresses. Any attempts to use other addresses fail,
    56    and attempts to use wildcard addresses silently use the jailed address instead. For
    57    IPv4 the first address given will be used as the source address when source address selection on
    58    unbound sockets cannot find a better match. It is only possible to start multiple jails with
    59    the same IP address if none of the jails has more than this
    60    single overlapping IP address assigned to itself.
    61  
    62  - `Allow_raw_sockets` - (Optional) The jail root is allowed to create raw sockets. Setting
    63    this parameter allows utilities like ping(8) and traceroute(8) to operate inside the jail.
    64    If this is set, the source IP addresses are enforced to comply with the IP address bound to the jail,
    65    regardless of whether or not the IP_HDRINCL flag has been set on the socket.
    66    Since raw sockets can be used to configure and interact with various network subsystems, extra caution
    67    should be used where privileged access to jails is given out to untrusted parties.
    68  
    69  ## Resource Isolation
    70  
    71  Resource isolation on jails is enforced by [RCTL(8)][rctl-doc] all parameters for resource control
    72  are supported.
    73  
    74  - `Rctl` - (Optional) Set resource limits on the jail, for a list of currently supported parameters, please refer to the [Parameter Documentation][parameter-doc].
    75  
    76        	* `Vmemoryuse`   - (Optional) Address space limit,in bytes
    77        	* `Cputime`      - (Optional) CPU time, in seconds
    78        	* `Datasize`     - (Optional)  data	size, in bytes
    79        	* `Stacksize`    - (Optional   stack size, in bytes
    80        	* `Coredumpsize` - (Optional)	   core	dump size, in bytes
    81        	* `Memoryuse`    - (Optional)	   resident set size, in bytes
    82        	* `Memorylocked` - (Optional)	   locked memory, in bytes
    83        	* `Maxproc`      - (Optional)		   number of processes
    84        	* `Openfiles`    - (Optional)	   file	descriptor table size
    85        	* `Vmemoryuse`   - (Optional) 	   address space limit,in bytes
    86        	* `Pseudoterminals`  - (Optional)	   number of PTYs
    87        	* `Swapuse`  - (Optional)		   swap	space that may be reserved or used, in bytes
    88        	* `Nthr`  - (Optional)		   number of threads
    89        	* `Msgqqueued`  - (Optional) 	   number of queued SysV messages
    90        	* `Msgqsize`  - (Optional)	   SysV	message	queue size, in bytes
    91        	* `Nmsgq`  - (Optional)		   number of SysV message queues
    92        	* `Nsem`  - (Optional)		   number of SysV semaphores
    93        	* `Nsemop`  - (Optional)		   number of SysV semaphores modified in a single semop(2) call
    94        	* `Nshm`  - (Optional)		   number of SysV shared memory	segments
    95        	* `Shmsize`  - (Optional)		   SysV	shared memory size, in bytes
    96        	* `Wallclock`  - (Optional)	   wallclock time, in seconds
    97        	* `Pcpu`  - (Optional)		   %CPU, in percents of	a single CPU core
    98        	* `Readbps`  - (Optional)		   filesystem reads, in	bytes per second
    99        	* `Writebps`  - (Optional)	   filesystem writes, in bytes per second
   100        	* `Readiops`  - (Optional)	   filesystem reads, in	operations per second
   101        	* `Writeiops`  - (Optional)	   filesystem writes, in operations per	second
   102  
   103  ## Networking
   104  
   105  The job spec could specify the `Ip4addr` parameter to add the jail's ip address to an specific interface at jail
   106  startup or the `Vnet` parameter to create a virtual network stack. Please refer to [JAIL(8)][jail(8)] for more details.
   107  
   108  - `vnet jail` - Example taken from Lucas, Michael W. FreeBSD Mastery: Jails (IT Mastery Book 15).
   109  
   110  ```hcl
   111   task "test01" {
   112        driver = "jail-task-driver"
   113        config {
   114  		Path    = "/zroot/iocage/jails/myjail/root"
   115  		Host_hostname = "nomad00"
   116  		Exec_clean = true
   117  		Exec_start = "sh /etc/rc"
   118  		Exec_stop = "sh /etc/rc.shutdown"
   119  		Mount_devfs = true
   120  		Exec_prestart = "logger trying to start "
   121  		Exec_poststart = "logger jail has started"
   122  		Exec_prestop = "logger shutting down jail "
   123  		Exec_poststop = "logger has shut down jail "
   124  		Exec_consolelog ="/var/tmp/vnet-example"
   125  		Vnet = true
   126  		Vnet_nic = "e0b_loghost"
   127  		Exec_prestart = "/usr/share/examples/jails/jib addm loghost em1"
   128  		Exec_poststop = "/usr/share/examples/jails/jib destroy loghost "
   129        }
   130      }
   131  ```
   132  
   133  ## Client Requirements
   134  
   135  `jail-task-driver` requires the following:
   136  
   137  - 64-bit FreeBSD 12.0-RELEASE host
   138  - The FreeBSD's Nomad binary
   139  - The jail-task-driver binary placed in the [plugin_dir][plugin_dir] directory.
   140  - If resource control is going be used then [RACCT][racct-doc] must be enabled
   141  
   142  [jail-task-driver]: https://github.com/cneira/jail-task-driver/releases
   143  [jail-task-guide]: https://github.com/cneira/jail-task-driver#installation
   144  [jail(8)]: https://www.freebsd.org/cgi/man.cgi?jail(8)
   145  [racct-doc]: https://www.freebsd.org/doc/handbook/security-resourcelimits.html
   146  [rctl-doc]: https://www.freebsd.org/doc/handbook/security-resourcelimits.html
   147  [parameter-doc]: https://github.com/cneira/jail-task-driver/blob/master/Parameters.md
   148  [plugin_dir]: /docs/configuration#plugin_dir
   149  [allocation working directory]: /docs/runtime/environment#task-directories 'Task Directories'