Articles

Jail search and shell

In the JailOps console, Ctrl+K finds any jail by name, address, label or app, labels filter the jail list, and one click opens a jail's shell, with bash and a prompt you can tell from the host. The command line next to each step, the permissions, and what was tested.

Find a jail: the quick switcher

Ctrl+K, or Cmd+K on a Mac.

With twenty jails, scrolling a list works. With two hundred in five projects, you want to type. The host console has a quick switcher: Ctrl+K (Cmd+K), / anywhere no text is being typed, or the Search button in the side bar (in the top bar on a phone).

  • It finds jails by name, image, address, label and app, and also the app catalog, images, networks, projects, storage and the console's own pages.
  • Labels work as terms: env=prod (the label has this value), team: (the jail has the label), -tier=edge (leave those out).
  • The order is whole name first, then prefix, then part of the name, then anywhere, then letters in order. Empty, it shows what you opened recently.
  • Every project searches all the projects you may use, not only the current one.
  • A jail row has its quick actions: Shell (Shift+Enter), Logs (Alt+L), and Start or Stop (Alt+S; stopping asks first).

It is a dialog with a combobox and grouped results that a screen reader announces, each group capped with a "refine your search" line, and it searches in the browser's memory, so thousands of jails stay fast.

The quick switcher of the JailOps host console in dark theme over the jail list, with the query env=prod: a group Jails with api, cache, db, git, mail, metrics, proxy and vault, each with its state, its labels as chips and its image, a Shell button on each running jail, Logs and Stop on the selected one, 2 more: refine your search, and the keys at the bottom: move, open, shell, logs, start or stop, close. Demo data.The quick switcher of the JailOps host console in light theme over the jail list, with the query env=prod: a group Jails with api, cache, db, git, mail, metrics, proxy and vault, each with its state, its labels as chips and its image, a Shell button on each running jail, Logs and Stop on the selected one, 2 more: refine your search, and the keys at the bottom: move, open, shell, logs, start or stop, close. Demo data.
The quick switcher with a label query: every jail with env=prod, with its actions. Demo data.

Labels you can see and change

key=value on a jail.

A label is a key=value pair on a jail: env=prod, team=web, tier=edge. JailOps gives most labels no meaning of its own; they are how you group jails, and what backup policies, log forwarding, the merged log view and bulk commands select. A changed label changes what they select: removing backup=yes takes a jail out of the nightly backup.

  • Chips in the jail list, on the jail page and in the installed apps. A click on a chip filters the list by it.
  • The list's filter reads env=prod, env:, -team=web and plain words, suggests the keys and values your jails carry, and lives in the address: /jails?q=env%3Dprod is a link you can share, and the back button undoes a chip. The last filter is remembered per user and project.
  • Edit labels on the jail page, Labels for the jails selected in the list (set or remove one on all of them), and a labels field in Create jail.
  • The rules are the server's. The console checks a label before it sends it, on the same test cases as the server. Keys that start with jailops. are set by JailOps (an app installation writes jailops.app): the console shows them and does not offer to change them.
The jail list of the JailOps host console in dark theme, filtered by env=prod team=web: the two terms as removable chips, 4 of 13 jails, and the rows api, cache, proxy and web, each with its labels as chips, its image freebsd-15-1, its address and a Shell button. Demo data.The jail list of the JailOps host console in light theme, filtered by env=prod team=web: the two terms as removable chips, 4 of 13 jails, and the rows api, cache, proxy and web, each with its labels as chips, its image freebsd-15-1, its address and a Shell button. Demo data.
The jail list filtered by two labels; the filter is in the address. Demo data.

Open the jail's shell

One click, or one link.

Every running jail has a Shell button, in the list and on its page. /jails/NAME/shell opens the Console tab already connected, so a link to a jail's shell can go in a ticket or a runbook. A stopped jail offers Start and open shell: it starts the jail and connects once it runs.

The Console tab says which shell runs as whom, and shows the same session's command line, jailops shell NAME --project P, with a copy button. A jail page opens on the tab you used last for that jail.

The Console tab of the jail web in the JailOps host console in dark theme: /usr/local/bin/bash as root, 125 x 25, Connected; a terminal with the light blue prompt root@web:/# and the output of hostname and uname -a; below it the same shell from the command line, jailops shell web --project web, with a Copy command button. Demo data.The Console tab of the jail web in the JailOps host console in light theme: /usr/local/bin/bash as root, 125 x 25, Connected; a terminal with the light blue prompt root@web:/# and the output of hostname and uname -a; below it the same shell from the command line, jailops shell web --project web, with a Copy command button. Demo data.
The jail's shell in the console, and the same shell from the command line. Demo data.

bash and a prompt you can tell apart

A new FreeBSD jail comes with bash, installed from the host's package repository at its first start (pkg -r ROOT install -y bash, as an app installation does), and a light blue prompt for every user of the jail that says where you are. Two small files JailOps owns, /usr/local/etc/profile.d/jailops-env.sh and jailops-prompt.sh, are read through a marked block at the top of /usr/local/etc/profile and /usr/local/etc/bash.bashrc. All of it lives in /usr/local, so it survives an upgrade of the jail, and a user's own ~/.bashrc wins.

The prompt shows the jail, and in grey in square brackets its project and the host it runs on, so an ssh login or jailops shell tells you at once which jail of which project on which host you are in:

in the jail
root@web [shop/babel]:/usr/local/etc#
ann@web [shop/babel]:~$

The jail's host name stays what it is, the jail's name. The place is in three variables that every interactive bash of the jail has: JAILOPS_JAIL, JAILOPS_PROJECT and JAILOPS_HOST (the host's short name). They come from the jail itself: the host starts it with three parameters, and FreeBSD gives them to the jail as the read-only sysctl security.jail.env, which jls -j web env shows on the host and sysctl -n security.jail.env shows in any shell inside the jail, so they stay right after a rename and when the jail moves to another host. The prompt reads the variables each time it is shown, and your own ~/.bashrc, a script run by hand or a prompt of your own can use them too. A shell that is not a bash, such as sh or ssh host command, does not have the variables but can read the sysctl. user@jail is in the colour of jails.prompt_color: set it once per host, red for production and green for test, and the colour tells the hosts apart. To write a prompt of your own, use the words {jail}, {project} and {host}, which read the variables. short is the same prompt without the grey tag, and none removes the prompt and keeps the variables. For one jail, or for every new jail of a host:

one jail, or every new jail of a host
$ jailops config set web prompt short
$ jailops config set web prompt '\u@{jail} [{project}/{host}]:\w\$ '

# /usr/local/etc/jailops/jailopsd.yaml
jails:
  prompt: default
  prompt_color: 196    # user@jail in red on a production host

Two keys of the jail change it: shell (bash, sh or a path) and prompt (default, short, none or a PS1 text). A prompt is checked against an allow-list, so nothing in it can run a command. An existing jail is not changed on its own: Install bash and the prompt on its Console tab, or jailops jail shell-setup NAME, gives it what a new jail gets. Linux jails keep the shell and prompt of their distribution.

The Configuration tab of the jail web in the JailOps host console in dark theme: the keys hostname, image freebsd-15-1, profiles, prompt set to default with its explanation, and shell set to /usr/local/bin/bash with its explanation. Demo data.The Configuration tab of the jail web in the JailOps host console in light theme: the keys hostname, image freebsd-15-1, profiles, prompt set to default with its explanation, and shell set to /usr/local/bin/bash with its explanation. Demo data.
The keys shell and prompt on the Configuration tab. Demo data.

The command line next to each step

The same API underneath.

Each console step and the jailops command that does the same
In the consoleOn the command line
Quick switcher, a part of a namejailops list 'w*'
Filter by labelsjailops list -l env=prod -l team=web
Edit labels: set, removejailops label web tier=edge, jailops label web tier-
Create jail with labelsjailops create web --image freebsd-15-1 --storage default --label env=prod
Shelljailops shell web --project web
Logs (Alt+L)jailops jail logs web, or every jail with a label: jailops logs -l env=prod
Start or Stop (Alt+S)jailops start web, or by label: jailops stop -l env=staging
Install bash and the promptjailops jail shell-setup web
The keys shell and promptjailops set web shell sh, jailops config set web prompt none

The console's key: and -key=value terms filter in the browser; the command line's -l takes key=value only. Over the API, a label change is a merge patch of the jail: PATCH /api/v1/jails/{name} with {"metadata": {"labels": {"tier": "edge"}}}.

Who may open a shell

The same rights as the command line.

  • A shell needs the operator role (or admin) in the jail's project, the right jailops exec needs. The Console tab and the Shell buttons are offered only to such an identity, on a server with the jail_console extension. Nothing changed on the server for this.
  • Every session is recorded in the audit log, as a jailops shell from the command line is. What you type runs as root in the jail.
  • Changing labels needs the admin role in the jail's project; reading them is part of reading the jail.
  • Every project in the switcher searches only the projects your identity may use.

There is no second password before a shell: opening one is the same right as jailops exec, which your role in the project already grants, so a second prompt would guard nothing the role does not already allow. A permission for shells that is separate from starting and stopping is on the list of things to build if people ask for it.

The full rules

For reference.

The full rules are in docs/labels.md and docs/shell.md.

More articles

Try it on one server.

Try the console from the screenshots, install on a clean FreeBSD 15.1 machine, or add JailOps to a host you already run.