JAILCFG(8) FreeBSD System Manager's Manual JAILCFG(8) NAME jailcfg - set up jail configuration SYNOPSIS jailcfg -j jailname jailcfg -j jailname subcommand jailcfg -j jailname -f command_file jailcfg help DESCRIPTION The jailcfg utility creates and modifies the configuration of a jail. Jail configuration consists of a number of resources and properties. To simplify the user interface, jailcfg uses the concept of a scope. The default scope is global. The following synopsis of the jailcfg command is for interactive usage: jailcfg -j jailname subcommand Parameters changed through jailcfg do not affect a running jail. The jail must be rebooted for the changes to take effect. In addition to creating and modifying a jail, the jailcfg utility can also be used to persistently specify the resource management settings for the global jail. In the following text, "rctl" is used as an abbreviation for "resource control". See resource_controls(5). Every jail is configured with an associated brand. The brand determines the user-level environment used within the jail, as well as various behaviors for the jail when it is installed, boots, or is shutdown. Once a jail has been installed the brand cannot be changed. The default brand is determined by the installed distribution in the global jail. Some brands do not support all of the jailcfg properties and resources. See the brand-specific man page for more details on each brand. For an overview of brands, see the brands(5) man page. Resources The following resource types are supported: attr Generic attribute. capped-cpu Limits for CPU usage. capped-memory Limits for physical, swap, and locked memory. dataset ZFS dataset. dedicated-cpu Subset of the system's processors dedicated to this jail while it is running. device Device. fs file-system net Network interface. rctl Resource control. Properties Each resource type has one or more properties. There are also some global properties, that is, properties of the configuration as a whole, rather than of some particular resource. The following properties are supported: (global) jailname (global) jailpath (global) autoboot (global) bootargs (global) pool (global) limitpriv (global) brand (global) cpu-shares (global) hostid (global) max-lwps (global) max-msg-ids (global) max-sem-ids (global) max-shm-ids (global) max-shm-memory (global) scheduling-class (global) fs-allowed fs dir, special, raw, type, options net address, physical, defrouter device match rctl name, value attr name, type, value dataset name dedicated-cpu ncpus, importance capped-memory physical, swap, locked capped-cpu ncpus As for the property values which are paired with these names, they are either simple, complex, or lists. The type allowed is property- specific. Simple values are strings, optionally enclosed within quotation marks. Complex values have the syntax: (<name>=<value>,<name>=<value>,...) where each <value> is simple, and the <name> strings are unique within a given property. Lists have the syntax: [<value>,...] where each <value> is either simple or complex. A list of a single value (either simple or complex) is equivalent to specifying that value without the list syntax. That is, "foo" is equivalent to "[foo]". A list can be empty (denoted by "[]"). In interpreting property values, jailcfg accepts regular expressions as specified in fnmatch(5). See EXAMPLES. The property types are described as follows: global: jailname The name of the jail. global: jailpath Path to jail's file system. global: autoboot Boolean indicating that a jail should be booted automatically at system boot. global: bootargs Arguments (options) to be passed to the jail bootup, unless options are supplied to the "jailadm boot" command, in which case those take precedence. The valid arguments are described in jailadm(8). global: pool Name of the resource pool that this jail must be bound to when booted. This property is incompatible with the dedicated-cpu resource. global: limitpriv The maximum set of privileges any process in this jail can obtain. The property should consist of a comma-separated privilege set specification as described in priv_str_to_set(3C). Privileges can be excluded from the resulting set by preceding their names with a dash (-) or an exclamation point (!). The special privilege string "jail" is not supported in this context. If the special string "default" occurs as the first token in the property, it expands into a safe set of privileges that preserve the resource and security isolation described in jails(5). A missing or empty property is equivalent to this same set of safe privileges. The system administrator must take extreme care when configuring privileges for a jail. Some privileges cannot be excluded through this mechanism as they are required in order to boot a jail. In addition, there are certain privileges which cannot be given to a jail as doing so would allow processes inside a jail to unduly affect processes in other jails. jailadm(1M) indicates when an invalid privilege has been added or removed from a jail's privilege set when an attempt is made to either "boot" or "ready" the jail. See privileges(5) for a description of privileges. The command "ppriv -l" (see ppriv(1)) produces a list of all Solaris privileges. You can specify privileges as they are displayed by ppriv. In privileges(5), privileges are listed in the form PRIV_privilege_name. For example, the privilege sys_time, as you would specify it in this property, is listed in privileges(5) as PRIV_SYS_TIME. global: brand The jail's brand type. global: ip-type A jail can either share the IP instance with the global jail, which is the default, or have its own exclusive instance of IP. This property takes the values shared and exclusive. global: hostid A jail can emulate a 32-bit host identifier to ease system consolidation. A jail's hostid property is empty by default, meaning that the jail does not emulate a host identifier. Jail host identifiers must be hexadecimal values between 0 and FFFFFFFE. A 0x or 0X prefix is optional. Both uppercase and lowercase hexadecimal digits are acceptable. fs: dir, special, raw, type, options Values needed to determine how, where, and so forth to mount file systems. See mount(1M), mount(2), fsck(1M), and vfstab(4). net: address, physical, defrouter The network address and physical interface name of the network interface. The network address is one of: o a valid IPv4 address, optionally followed by "/" and a prefix length; o a valid IPv6 address, which must be followed by "/" and a prefix length; o a host name which resolves to an IPv4 address. Note that host names that resolve to IPv6 addresses are not supported. The physical interface name is the network interface name. The default router is specified similarly to the network address except that it must not be followed by a / (slash) and a network prefix length. A jail can be configured to be either exclusive-IP or shared-IP. For a shared-IP jail, you must set both the physical and address properties; setting the default router is optional. The interface specified in the physical property must be plumbed in the global jail prior to booting the non-global jail. However, if the interface is not used by the global jail, it should be configured down in the global jail, and the default router for the interface should be specified here. For an exclusive-IP jail, the physical property must be set and the address and default router properties cannot be set. device: match Device name to match. rctl: name, value The name and priv/limit/action triple of a resource control. See prctl(1) and rctladm(1M). The preferred way to set rctl values is to use the global property name associated with a specific rctl. attr: name, type, value The name, type and value of a generic attribute. The type must be one of int, uint, boolean or string, and the value must be of that type. uint means unsigned , that is, a non-negative integer. dataset: name The name of a ZFS dataset to be accessed from within the jail. See zfs(1M). global: cpu-shares The number of Fair Share Scheduler (FSS) shares to allocate to this jail. This property is incompatible with the dedicated-cpu resource. This property is the preferred way to set the jail.cpu- shares rctl. global: max-lwps The maximum number of LWPs simultaneously available to this jail. This property is the preferred way to set the jail.max-lwps rctl. global: max-msg-ids The maximum number of message queue IDs allowed for this jail. This property is the preferred way to set the jail.max-msg-ids rctl. global: max-sem-ids The maximum number of semaphore IDs allowed for this jail. This property is the preferred way to set the jail.max-sem-ids rctl. global: max-shm-ids The maximum number of shared memory IDs allowed for this jail. This property is the preferred way to set the jail.max-shm-ids rctl. global: max-shm-memory The maximum amount of shared memory allowed for this jail. This property is the preferred way to set the jail.max-shm-memory rctl. A scale (K, M, G, T) can be applied to the value for this number (for example, 1M is one megabyte). global: scheduling-class Specifies the scheduling class used for processes running in a jail. When this property is not specified, the scheduling class is established as follows: o If the cpu-shares property or equivalent rctl is set, the scheduling class FSS is used. o If neither cpu-shares nor the equivalent rctl is set and the jail's pool property references a pool that has a default scheduling class, that class is used. o Under any other conditions, the system default scheduling class is used. dedicated-cpu: ncpus, importance The number of CPUs that should be assigned for this jail's exclusive use. The jail will create a pool and processor set when it boots. See pooladm(1M) and poolcfg(1M) for more information on resource pools. The ncpu property can specify a single value or a range (for example, 1-4) of processors. The importance property is optional; if set, it will specify the pset.importance value for use by poold(1M). If this resource is used, there must be enough free processors to allocate to this jail when it boots or the jail will not boot. The processors assigned to this jail will not be available for the use of the global jail or other jails. This resource is incompatible with both the pool and cpu-shares properties. Only a single instance of this resource can be added to the jail. capped-memory: physical, swap, locked The caps on the memory that can be used by this jail. A scale (K, M, G, T) can be applied to the value for each of these numbers (for example, 1M is one megabyte). Each of these properties is optional but at least one property must be set when adding this resource. Only a single instance of this resource can be added to the jail. The physical property sets the max-rss for this jail. This will be enforced by rcapd(1M) running in the global jail. The swap property is the preferred way to set the jail.max-swap rctl. The locked property is the preferred way to set the jail.max-locked- memory rctl. capped-cpu: ncpus Sets a limit on the amount of CPU time that can be used by a jail. The unit used translates to the percentage of a single CPU that can be used by all user threads in a jail, expressed as a fraction (for example, .75) or a mixed number (whole number and fraction, for example, 1.25). An ncpu value of 1 means 100% of a CPU, a value of 1.25 means 125%, .75 mean 75%, and so forth. When projects within a capped jail have their own caps, the minimum value takes precedence. The capped-cpu property is an alias for jail.cpu-cap resource control and is related to the jail.cpu-cap resource control. See resource_controls(5). global: fs-allowed A comma-separated list of additional filesystems that may be mounted within the jail; for example "ufs,pcfs". By default, only hsfs(7fs) and network filesystems can be mounted. If the first entry in the list is "-" then that disables all of the default filesystems. If any filesystems are listed after "-" then only those filesystems can be mounted. This property does not apply to filesystems mounted into the jail via "add fs" or "add dataset". WARNING: allowing filesystem mounts other than the default may allow the jail administrator to compromise the system with a malicious filesystem image, and is not supported. The following table summarizes resources, property-names, and types: resource property-name type (global) jailname simple (global) jailpath simple (global) autoboot simple (global) bootargs simple (global) pool simple (global) limitpriv simple (global) brand simple (global) ip-type simple (global) hostid simple (global) cpu-shares simple (global) max-lwps simple (global) max-msg-ids simple (global) max-sem-ids simple (global) max-shm-ids simple (global) max-shm-memory simple (global) scheduling-class simple fs dir simple special simple raw simple type simple options list of simple net address simple physical simple device match simple rctl name simple value list of complex attr name simple type simple value simple dataset name simple dedicated-cpu ncpus simple or range importance simple capped-memory physical simple with scale swap simple with scale locked simple with scale capped-cpu ncpus simple To further specify things, the breakdown of the complex property "value" of the "rctl" resource type, it consists of three name/value pairs, the names being "priv", "limit" and "action", each of which takes a simple value. The "name" property of an "attr" resource is syntactically restricted in a fashion similar but not identical to jail names: it must begin with an alphanumeric, and can contain alphanumerics plus the hyphen (-), underscore (_), and dot (.) characters. Attribute names beginning with "jail" are reserved for use by the system. Finally, the "autoboot" global property must have a value of "true" or "false". OPTIONS The following options are supported: -f command_file Specify the name of jailcfg command file. command_file is a text file of jailcfg subcommands, one per line. -j jailname Specify the name of a jail. Jail names are case sensitive. Jail names must begin with an alphanumeric character and can contain alphanumeric characters, the underscore (_) the hyphen (-), and the dot (.). SUBCOMMANDS You can use the add and select subcommands to select a specific resource, at which point the scope changes to that resource. The end and cancel subcommands are used to complete the resource specification, at which time the scope is reverted back to global. Certain subcommands, such as add, remove and set, have different semantics in each scope. jailcfg supports a semicolon-separated list of subcommands. For example: # jailcfg -j myjail "add net; set physical=myvnic; end" Subcommands which can result in destructive actions or loss of work have an -F option to force the action. If input is from a terminal device, the user is prompted when appropriate if such a command is given without the -F option otherwise, if such a command is given without the -F option, the action is disallowed, with a diagnostic message written to standard error. The following subcommands are supported: add resource-type (global scope) add property-name property-value (resource scope) In the global scope, begin the specification for a given resource type. The scope is changed to that resource type. In the resource scope, add a property of the given name with the given value. The syntax for property values varies with different property types. In general, it is a simple value or a list of simple values enclosed in square brackets, separated by commas ([foo,bar,baz]). See PROPERTIES. cancel End the resource specification and reset scope to global. Abandons any partially specified resources. cancel is only applicable in the resource scope. clear property-name Clear the value for the property. commit Commit the current configuration from memory to stable storage. The configuration must be committed to be used by jailadm. Until the in-memory configuration is committed, you can remove changes with the revert subcommand. The commit operation is attempted automatically upon completion of a jailcfg session. Since a configuration must be correct to be committed, this operation automatically does a verify. create [-F] [ -a path |-b | -t template] Create an in-memory configuration for the specified jail. Use create to begin to configure a new jail. See commit for saving this to stable storage. If you are overwriting an existing configuration, specify the -F option to force the action. Specify the -t template option to create a configuration identical to template, where template is the name of a configured jail. Use the -a path option to facilitate configuring a detached jail on a new host. The path parameter is the jailpath location of a detached jail that has been moved on to this new host. Once the detached jail is configured, it should be installed using the "jailadm attach" command (see jailadm(8)). All validation of the new jail happens during the attach process, not during jail configuration. Use the -b option to create a blank configuration. Without arguments, create applies the Sun default settings. delete [-F] Delete the specified configuration from memory and stable storage. This action is instantaneous, no commit is necessary. A deleted configuration cannot be reverted. Specify the -F option to force the action. end End the resource specification. This subcommand is only applicable in the resource scope. jailcfg checks to make sure the current resource is completely specified. If so, it is added to the in- memory configuration (see commit for saving this to stable storage) and the scope reverts to global. If the specification is incomplete, it issues an appropriate error message. export [-f output-file] Print configuration to standard output. Use the -f option to print the configuration to output-file. This option produces output in a form suitable for use in a command file. help [usage] [subcommand] [syntax] [command-name] Print general help or help about given topic. info jailname | jailpath | autoboot | brand | pool | limitpriv info [resource-type [property-name=property-value]*] Display information about the current configuration. If resource- type is specified, displays only information about resources of the relevant type. If any property-name value pairs are specified, displays only information about resources meeting the given criteria. In the resource scope, any arguments are ignored, and info displays information about the resource which is currently being added or modified. remove resource-type{property-name=property -value}(global scope) In the global scope, removes the specified resource. The [] syntax means 0 or more of whatever is inside the square braces. If you want only to remove a single instance of the resource, you must specify enough property name-value pairs for the resource to be uniquely identified. If no property name-value pairs are specified, all instances will be removed. If there is more than one pair is specified, a confirmation is required, unless you use the -F option. select resource-type {property-name=property-value} Select the resource of the given type which matches the given property-name property-value pair criteria, for modification. This subcommand is applicable only in the global scope. The scope is changed to that resource type. The {} syntax means 1 or more of whatever is inside the curly braces. You must specify enough property -name property-value pairs for the resource to be uniquely identified. set property-name=property-value Set a given property name to the given value. Some properties (for example, jailname and jailpath) are global while others are resource-specific. This subcommand is applicable in both the global and resource scopes. verify Verify the current configuration for correctness: o All resources have all of their required properties specified. o A jailpath is specified. revert [-F] Revert the configuration back to the last committed state. The -F option can be used to force the action. exit [-F] Exit the jailcfg session. A commit is automatically attempted if needed. You can also use an EOF character to exit jailcfg. The -F option can be used to force the action. EXAMPLES Example 1 Creating the Environment for a New Jail In the following example, jailcfg creates the environment for a new jail. /usr/local is loopback mounted from the global jail into /opt/local. /opt/sfw is loopback mounted from the global jail, three logical network interfaces are added, and a limit on the number of fair-share scheduler (FSS) CPU shares for a jail is set using the rctl resource type. The example also shows how to select a given resource for modification. example# jailcfg -j myjail3 my-jail3: No such jail configured Use 'create' to begin configuring a new jail. jailcfg:myjail3> create jailcfg:myjail3> set jailpath=/export/home/my-jail3 jailcfg:myjail3> set autoboot=true jailcfg:myjail3> add fs jailcfg:myjail3:fs> set dir=/usr/local jailcfg:myjail3:fs> set special=/opt/local jailcfg:myjail3:fs> set type=lofs jailcfg:myjail3:fs> add options [ro,nodevices] jailcfg:myjail3:fs> end jailcfg:myjail3> add fs jailcfg:myjail3:fs> set dir=/mnt jailcfg:myjail3:fs> set special=/dev/dsk/c0t0d0s7 jailcfg:myjail3:fs> set raw=/dev/rdsk/c0t0d0s7 jailcfg:myjail3:fs> set type=ufs jailcfg:myjail3:fs> end jailcfg:myjail3> add net jailcfg:myjail3:net> set address=192.168.0.1/24 jailcfg:myjail3:net> set physical=eri0 jailcfg:myjail3:net> end jailcfg:myjail3> add net jailcfg:myjail3:net> set address=192.168.1.2/24 jailcfg:myjail3:net> set physical=eri0 jailcfg:myjail3:net> end jailcfg:myjail3> add net jailcfg:myjail3:net> set address=192.168.2.3/24 jailcfg:myjail3:net> set physical=eri0 jailcfg:myjail3:net> end jailcfg:my-jail3> set cpu-shares=5 jailcfg:my-jail3> add capped-memory jailcfg:my-jail3:capped-memory> set physical=50m jailcfg:my-jail3:capped-memory> set swap=100m jailcfg:my-jail3:capped-memory> end jailcfg:myjail3> exit Example 2 Creating a Non-Native Jail The following example creates a new Linux jail: example# jailcfg -j lxjail lxjail: No such jail configured Use 'create' to begin configuring a new jail jailcfg:lxjail> create -t SUNWlx jailcfg:lxjail> set jailpath=/export/jails/lxjail jailcfg:lxjail> set autoboot=true jailcfg:lxjail> exit Example 3 Creating an Exclusive-IP Jail The following example creates a jail that is granted exclusive access to bge1 and bge33000 and that is isolated at the IP layer from the other jails configured on the system. example# jailcfg -j excl excl: No such jail configured Use 'create' to begin configuring a new jail jailcfg:excl> create jailcfg:excl> set jailpath=/export/jails/excl jailcfg:excl> set ip-type=exclusive jailcfg:excl> add net jailcfg:excl:net> set physical=bge1 jailcfg:excl:net> end jailcfg:excl> add net jailcfg:excl:net> set physical=bge33000 jailcfg:excl:net> end jailcfg:excl> exit Example 4 Associating a Jail with a Resource Pool The following example shows how to associate an existing jail with an existing resource pool: example# jailcfg -j myjail jailcfg:myjail> set pool=mypool jailcfg:myjail> exit For more information about resource pools, see pooladm(1M) and poolcfg(1M). Example 5 Changing the Name of a Jail The following example shows how to change the name of an existing jail: example# jailcfg -j myjail jailcfg:myjail> set jailname=myjail2 jailcfg:myjail2> exit Example 6 Changing the Privilege Set of a Jail The following example shows how to change the set of privileges an existing jail's processes will be limited to the next time the jail is booted. In this particular case, the privilege set will be the standard safe set of privileges a jail normally has along with the privilege to change the system date and time: example# jailcfg -j myjail jailcfg:myjail> set limitpriv="default,sys_time" jailcfg:myjail2> exit Example 7 Setting the jail.cpu-shares Property for the Global Jail The following command sets the jail.cpu-shares property for the global jail: example# jailcfg -j global jailcfg:global> set cpu-shares=5 jailcfg:global> exit Example 8 Using Pattern Matching The following commands illustrate jailcfg support for pattern matching. In the jail flexlm, enter: jailcfg:flexlm> add device jailcfg:flexlm:device> set match="/dev/cua/a00[2-5]" jailcfg:flexlm:device> end In the global jail, enter: global# ls /dev/cua a a000 a001 a002 a003 a004 a005 a006 a007 b In the jail flexlm, enter: flexlm# ls /dev/cua a002 a003 a004 a005 Example 9 Setting a Cap for a Jail to Three CPUs The following sequence uses the jailcfg command to set the CPU cap for a jail to three CPUs. jailcfg:myjail> add capped-cpu jailcfg:myjail>capped-cpu> set ncpus=3 jailcfg:myjail>capped-cpu>capped-cpu> end The preceding sequence, which uses the capped-cpu property, is equivalent to the following sequence, which makes use of the jail.cpu- cap resource control. jailcfg:myjail> add rctl jailcfg:myjail:rctl> set name=jail.cpu-cap jailcfg:myjail:rctl> add value (priv=privileged,limit=300,action=none) jailcfg:myjail:rctl> end Example 10 Using kstat to Monitor CPU Caps The following command displays information about all CPU caps. # kstat -n /cpucaps/ module: caps instance: 0 name: cpucaps_project_0 class: project_caps above_sec 0 below_sec 2157 crtime 821.048183159 maxusage 2 nwait 0 snaptime 235885.637253027 usage 0 value 18446743151372347932 jailname global module: caps instance: 0 name: cpucaps_project_1 class: project_caps above_sec 0 below_sec 0 crtime 225339.192787265 maxusage 5 nwait 0 snaptime 235885.637591677 usage 5 value 18446743151372347932 jailname global module: caps instance: 0 name: cpucaps_project_201 class: project_caps above_sec 0 below_sec 235105 crtime 780.37961782 maxusage 100 nwait 0 snaptime 235885.637789687 usage 43 value 100 jailname global module: caps instance: 0 name: cpucaps_project_202 class: project_caps above_sec 0 below_sec 235094 crtime 791.72983782 maxusage 100 nwait 0 snaptime 235885.637967512 usage 48 value 100 jailname global module: caps instance: 0 name: cpucaps_project_203 class: project_caps above_sec 0 below_sec 235034 crtime 852.104401481 maxusage 75 nwait 0 snaptime 235885.638144304 usage 47 value 100 jailname global module: caps instance: 0 name: cpucaps_project_86710 class: project_caps above_sec 22 below_sec 235166 crtime 698.441717859 maxusage 101 nwait 0 snaptime 235885.638319871 usage 54 value 100 jailname global module: caps instance: 0 name: cpucaps_jail_0 class: jail_caps above_sec 100733 below_sec 134332 crtime 821.048177123 maxusage 207 nwait 2 snaptime 235885.638497731 usage 199 value 200 jailname global module: caps instance: 1 name: cpucaps_project_0 class: project_caps above_sec 0 below_sec 0 crtime 225360.256448422 maxusage 7 nwait 0 snaptime 235885.638714404 usage 7 value 18446743151372347932 jailname test_001 module: caps instance: 1 name: cpucaps_jail_1 class: jail_caps above_sec 2 below_sec 10524 crtime 225360.256440278 maxusage 106 nwait 0 snaptime 235885.638896443 usage 7 value 100 jailname test_001 Example 11 Displaying CPU Caps for a Specific Jail or Project Using the kstat -c and -i options, you can display CPU caps for a specific jail or project, as below. The first command produces a display for a specific project, the second for the same project within jail 1. # kstat -c project_caps # kstat -c project_caps -i 1 EXIT STATUS The following exit values are returned: 0 Successful completion. 1 An error occurred. 2 Invalid usage. ATTRIBUTES See attributes(5) for descriptions of the following attributes: +--------------------+-----------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +--------------------+-----------------+ |Interface Stability | Volatile | +--------------------+-----------------+ SEE ALSO ppriv(1), prctl(1), zlogin(1), kstat(1M), mount(1M), pooladm(1M), poolcfg(1M), poold(1M), rcapd(1M), rctladm(1M), svcadm(1M), sysidtool(1M), zfs(1M), jailadm(1M), priv_str_to_set(3C), kstat(3KSTAT), vfstab(4), attributes(5), brands(5), fnmatch(5), lx(5), privileges(5), resource_controls(5), jails(5) System Administration Guide: Solaris Containers-Resource Management, and Solaris Jails NOTES All character data used by jailcfg must be in US-ASCII encoding. February 28, 2014 JAILCFG(8)