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 jail_set and jail_get can both create a new descriptor or reference an existing one. Passing a negative file number in the "desc" parameter indicates a request to create and return the descriptor in that parameter, and a zero/positive file number is expected to refer to an existing descriptor (any thing else is an error).
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.
Future plans, not yet done:
- A kevent interface for jail operations. At least jail death, possibly also attach, set, and child creation, as may be found useful.
- A mode where jail descriptor lifetime controls the prison itself, i.e. the prison is removed on the last close. 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.