roj (Run On Jail)
roj is a simple command-line tool that runs a command (login shell by default) in the given jail, either locally or over SSH.
Requirements
Python 3.10 or newer.
The host whose jails you are addressing must be FreeBSD, since roj drives
jls(8) and jexec(8) there. The machine you run roj from need only be
POSIX: with -H/--host everything is wrapped in ssh(1), so driving a
FreeBSD jail host from Linux or macOS works. Windows is not supported.
Installation
pip install roj
Examples:
roj abc
Runs a login shell in the local jail named abc.
roj -H adx ldap1 ps axl
Runs ps axl in the jail named ldap1 on the remote SSH host adx.
roj
Shows the jails on the local host.
roj -H pbsp
Shows the jails on the remote SSH host pbsp.
iocage Compatibility
The iocage jail manager
uses the ioc- prefix in its jail names.
To maintain compatibility with iocage,
by default roj shows and accepts jail names without the ioc- prefix.
Except if there is a conflict, then this prefix stripping behavior is disabled.
For example, if there is a jail ioc-xyz and there is also another jail xyz,
then the former is shown as and must be specified as ioc-test.
This behaviour can be disabled using the -f/--full flag.
SSH Host (-H/--host) Config
The hostname given to -H/--host is provided verbatim to
OpenSSH ssh(1)
so the name is subject to the usual
configuration
settings. For example, to use a shorthand alias, ex: roj -Hadx:
Host adx
HostName adx-florence.bop.gov
SSH Pseudo TTY Allocation
Just like OpenSSH ssh(1), by default login shells are run with a pseudo TTY,
and explicit commands are run without one.
This behavior can be overridden with --tty/--no-tty
(or -t/-T, as with ssh(1)).
Bash Completion
To use Bash completion support of roj:
complete -C 'roj --bash-complete' roj
It takes connection-related options (-H/--host and -u/--user)
so the following works as expected:
alias roj1='roj --host=server1'
complete -C `roj1 --bash-complete` roj1
Development
The dev toolchain is managed by uv, and
uv.lock is committed and authoritative.
uv sync # create .venv from uv.lock
uv run pytest # run the tests
uv run --python 3.14 pytest # ...on any supported version; uv fetches it
uv run ruff check . # lint
uv run ruff format . # format ("--check" to verify only)
uv build # build the sdist and wheel
If you change [project] or [dependency-groups] in pyproject.toml,
regenerate the lockfile with uv lock and commit it: CI runs uv lock --check
and fails on a stale one.
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file roj-0.3.0.tar.gz.
File metadata
- Download URL: roj-0.3.0.tar.gz
- Upload date:
- Size: 11.3 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
233505426c235a588aa48fd6a709a458e7d8116d6248b11a9770c95bfc8e37f9
|
|
| MD5 |
d42b048d3d1a6cc6911cd7b94fa444d5
|
|
| BLAKE2b-256 |
ea1256377ac1921f7d1af513f3827ffb6e71ebe3e0df9dfd71d961a828f2163a
|
Provenance
The following attestation bundles were made for roj-0.3.0.tar.gz:
Publisher:
release.yml on astralblue/roj
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
roj-0.3.0.tar.gz -
Subject digest:
233505426c235a588aa48fd6a709a458e7d8116d6248b11a9770c95bfc8e37f9 - Sigstore transparency entry: 2735041886
- Sigstore integration time:
-
Permalink:
astralblue/roj@1e62f5e102aa82f6512882b34127456a83de616d -
Branch / Tag:
refs/tags/v0.3.0 - Owner: https://github.com/astralblue
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@1e62f5e102aa82f6512882b34127456a83de616d -
Trigger Event:
push
-
Statement type:
File details
Details for the file roj-0.3.0-py3-none-any.whl.
File metadata
- Download URL: roj-0.3.0-py3-none-any.whl
- Upload date:
- Size: 6.2 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
12a03369fd4f0addc4cc2e426525ee1a0a3192950b3e2a7c2cb8be79d0a601eb
|
|
| MD5 |
dd63ca9d033547c53ddf7bb7e2401208
|
|
| BLAKE2b-256 |
efc4c414d67c2e7b3fe44263d974cd58ff6209c3ad8daee486f71bb1025fb3cb
|
Provenance
The following attestation bundles were made for roj-0.3.0-py3-none-any.whl:
Publisher:
release.yml on astralblue/roj
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
roj-0.3.0-py3-none-any.whl -
Subject digest:
12a03369fd4f0addc4cc2e426525ee1a0a3192950b3e2a7c2cb8be79d0a601eb - Sigstore transparency entry: 2735041977
- Sigstore integration time:
-
Permalink:
astralblue/roj@1e62f5e102aa82f6512882b34127456a83de616d -
Branch / Tag:
refs/tags/v0.3.0 - Owner: https://github.com/astralblue
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@1e62f5e102aa82f6512882b34127456a83de616d -
Trigger Event:
push
-
Statement type:
