Similar in spirit to process descriptors, jail descriptors are a reference to a jail using the file interface.
Jail descriptors can be created along with the underlying prison with jail_set(2), or fetched later with jail_get(2). They can then be used instead of the jid when a jail is used, via the new system calls jd_attach(2) and jd_remove(2), and also via the "desc" parameter in jail_get(2) and jail_set(2).
Note that jJail_set and jail_get can both create a new descriptor or reference an existing one, controlled by flags. JAIL_USE_DESC reads the desc parameter for a descriptor of the jail to operate on. JAIL_AT_DESC specifies instead the jail to operate //under//, for example the namespace where to find/create a jail, and the permissions to pass to it. Passing a negative file numbeJAIL_GET_DESC will return a new descriptor in the "desc" parameter indicates a request to create and return the descriptor in that(even in jail_set which normally doesn't return parameters), and a zero/positive file number is expected to refer to an existingJAIL_OWN_DESC with return that descriptor (any thing else is an error)with the sticky bit set.
Jail descriptors eliminate the race problem where a jail with a given ID may be destroyed and re-created, and not be the same jail that was referred to before. A descriptor always refers to a single jail over (and beyond) its lifetime, and it is an error to try use an existing descriptor to create a jail. So when a the jail on a descriptor claims to be dead, you can be sure it stays that way.
Permission for jail operations using descriptors is checked against the credentials of the process that first created the descriptor. This allows passing of jail descriptors to non-privileged users who could then for instance attach to a jail without being root. In addition to the privilege checks, the descriptor access mode is also checked, allowing per-user/group and per-operation controls. Read bits control jail_get, write bits control jail_set, and execute bits control jail_attach and the JAIL_AT_DEC flag.
Future planThe descriptor sticky bit is repurposed to indicate an owning descriptor, where the jail lifetime is now tied ("stuck") to the descriptor. When the descriptor closes, not yet done:do will the attached jail. This is similar to the default behavior of process descriptors.
* A kevent interface for jail operations.Jail descriptors can be followed via kevent, with the following note types:
- NOTE_JAIL_SET: jail_set has been called. It's up to the user to see what if anything has actually changed.
- NOTE_JAIL_ATTACH: a process has attached to the jail. The note data contains the pid.
At least- NOTE_JAIL_REMOVE: the jail death, possibly also attachhas been removed. The descriptor remains open, set, and child creation, as may be found usefulbut is no longer attached to the jail.
- NOTE_JAIL_CREATE: a child has been created under the watched jail. The note data contains the child's jid.
* A mode where jail descriptor lifetime controls the prison itselfFuture plans, i.e. the prison is removed on the last close.not yet done:
This is how all process descriptors already work.
* Finer controls (i.e. further constraint) on what a descriptor owner can do, via file properties (user/group and permissions) and capsicum flags.- Capsicum support
- documentation