2017-08-20 08:10:56 +08:00
.TH NSJAIL "1" "August 2017" "nsjail" "User Commands"
\"
.SH NAME
nsjail \- process isolation tool for linux
\"
.SH SYNOPSIS
\fI nsjail\fP [options] \fB \- \- \fR path_to_command [args]
\"
.SH DESCRIPTION
NsJail is a process isolation tool for Linux. It utilizes Linux namespace subsystem, resource limits, and the seccomp-bpf syscall filters of the Linux kernel
\"
.SH Options
.TP
\fB \- \- help\fR |\fB \- h\fR Help plz..
.TP
2017-10-12 14:53:10 +08:00
\fB \- \- mode\fR |\fB \- M\fR VALUE
Execution mode (default: o [MODE_STANDALONE_ONCE]):
2017-08-20 08:10:56 +08:00
.IP
\fB l\fR : Wait for connections on a TCP port (specified with \fB \- \- port\fR ) [MODE_LISTEN_TCP]
.PP
.IP
2018-06-13 05:27:31 +08:00
\fB o\fR : Launch a single process on the console using clone/execve [MODE_STANDALONE_ONCE]
2017-08-20 08:10:56 +08:00
.PP
.IP
2018-06-13 05:27:31 +08:00
\fB e\fR : Launch a single process on the console using execve [MODE_STANDALONE_EXECVE]
2017-08-20 08:10:56 +08:00
.PP
.IP
2018-06-13 05:27:31 +08:00
\fB r\fR : Launch a single process on the console with clone/execve, keep doing it forever [MODE_STANDALONE_RERUN]
2017-08-20 08:10:56 +08:00
.PP
.TP
\fB \- \- config\fR |\fB \- C\fR VALUE
2018-06-13 05:27:31 +08:00
Configuration file in the config.proto ProtoBuf format (see configs/ directory for examples)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- exec_file\fR |\fB \- x\fR VALUE
File to exec (default: argv[0])
.TP
2017-10-19 02:48:24 +08:00
\fB \- \- execute_fd\fR
Use execveat() to execute a file-descriptor instead of executing the binary path. In such case argv[0]/exec_file denotes a file path before mount namespacing
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- chroot\fR |\fB \- c\fR VALUE
Directory containing / of the jail (default: none)
.TP
\fB \- \- rw\fR
2017-10-12 14:53:10 +08:00
Mount chroot dir (/) R/W (default: R/O)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- user\fR |\fB \- u\fR VALUE
2020-07-07 20:07:22 +08:00
Username/uid of processes inside the jail (default: your current uid). You can also use inside_ns_uid:outside_ns_uid:count convention here. Can be specified multiple times
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- group\fR |\fB \- g\fR VALUE
2020-07-07 20:07:22 +08:00
Groupname/gid of processes inside the jail (default: your current gid). You can also use inside_ns_gid:global_ns_gid:count convention here. Can be specified multiple times
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- hostname\fR |\fB \- H\fR VALUE
UTS name (hostname) of the jail (default: 'NSJAIL')
.TP
\fB \- \- cwd\fR |\fB \- D\fR VALUE
Directory in the namespace the process will run (default: '/')
.TP
\fB \- \- port\fR |\fB \- p\fR VALUE
TCP port to bind to (enables MODE_LISTEN_TCP) (default: 0)
.TP
\fB \- \- bindhost\fR VALUE
IP address to bind the port to (only in [MODE_LISTEN_TCP]), (default: '::')
.TP
2021-02-10 06:13:35 +08:00
\fB \- \- max_conns\fR VALUE
Maximum number of connections across all IPs (only in [MODE_LISTEN_TCP]), (default: 0 (unlimited))
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- max_conns_per_ip\fR |\fB \- i\fR VALUE
Maximum number of connections per one IP (only in [MODE_LISTEN_TCP]), (default: 0 (unlimited))
.TP
\fB \- \- log\fR |\fB \- l\fR VALUE
Log file (default: use log_fd)
.TP
\fB \- \- log_fd\fR |\fB \- L\fR VALUE
Log FD (default: 2)
.TP
\fB \- \- time_limit\fR |\fB \- t\fR VALUE
Maximum time that a jail can exist, in seconds (default: 600)
.TP
\fB \- \- max_cpus\fR VALUE
Maximum number of CPUs a single jailed process can use (default: 0 'no limit')
.TP
\fB \- \- daemon\fR |\fB \- d\fR
Daemonize after start
.TP
\fB \- \- verbose\fR |\fB \- v\fR
Verbose output
.TP
\fB \- \- quiet\fR |\fB \- q\fR
2017-10-08 13:28:06 +08:00
Log warning and more important messages only
.TP
2019-01-09 18:24:34 +08:00
\fB \- \- really_quiet\fR |\fB \- Q\fR
2017-10-08 13:28:06 +08:00
Log fatal messages only
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- keep_env\fR |\fB \- e\fR
2019-08-29 04:18:58 +08:00
Pass all environment variables be passed process (default: all envars are cleared)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- env\fR |\fB \- E\fR VALUE
2019-08-29 04:18:58 +08:00
Additional environment variable (can be used multiple times). If the envar doesn't contain '=' (e.g. just the 'DISPLAY' string), the current envar value will be used
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- keep_caps\fR
2018-06-13 05:27:31 +08:00
Don't drop any capabilities
2017-08-20 08:10:56 +08:00
.TP
2018-02-24 15:39:36 +08:00
\fB \- \- cap\fR VALUE
2018-06-13 05:27:31 +08:00
Retain this capability, e.g. CAP_PTRACE (can be specified multiple times)
2018-02-24 15:39:36 +08:00
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- silent\fR
2018-06-13 05:27:31 +08:00
Redirect child process' fd:0/1/2 to /dev/null
2017-08-20 08:10:56 +08:00
.TP
2018-07-14 22:20:34 +08:00
\fB \- \- stderr_to_null\fR
Redirect FD=2 (STDERR_FILENO) to /dev/null
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- skip_setsid\fR
2018-06-13 05:27:31 +08:00
Don't call setsid(), allows for terminal signal handling in the sandboxed process. Dangerous
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- pass_fd\fR VALUE
2018-06-13 05:27:31 +08:00
Don't close this FD before executing the child process (can be specified multiple times), by default: 0/1/2 are kept open
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- disable_no_new_privs\fR
Don't set the prctl(NO_NEW_PRIVS, 1) (DANGEROUS)
.TP
\fB \- \- rlimit_as\fR VALUE
2021-09-15 00:57:30 +08:00
RLIMIT_AS in MB, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current soft limit, 'inf' for RLIM_INFINITY (default: 4096)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- rlimit_core\fR VALUE
2017-10-08 13:28:06 +08:00
RLIMIT_CORE in MB, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current limit, 'inf' for RLIM_INFINITY (default: 0)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- rlimit_cpu\fR VALUE
2017-10-08 13:28:06 +08:00
RLIMIT_CPU, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current soft limit, 'inf' for RLIM_INFINITY (default: 600)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- rlimit_fsize\fR VALUE
2017-10-08 13:28:06 +08:00
RLIMIT_FSIZE in MB, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current soft limit, 'inf' for RLIM_INFINITY (default: 1)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- rlimit_nofile\fR VALUE
2017-10-08 13:28:06 +08:00
RLIMIT_NOFILE, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current limit, 'inf' for RLIM_INFINITY (default: 32)
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- rlimit_nproc\fR VALUE
2017-10-08 13:28:06 +08:00
RLIMIT_NPROC, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current soft limit, 'inf' for RLIM_INFINITY (default: 'soft')
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- rlimit_stack\fR VALUE
2017-10-08 13:28:06 +08:00
RLIMIT_STACK in MB, 'max' or 'hard' for the current hard limit, 'def' or 'soft' for the current soft limit, 'inf' for RLIM_INFINITY (default: 'soft')
2017-08-20 08:10:56 +08:00
.TP
2019-08-05 18:25:22 +08:00
\fB \- \- disable_rlimits\fR
Disable all rlimits, default to limits set by parent
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- persona_addr_compat_layout\fR
personality(ADDR_COMPAT_LAYOUT)
.TP
\fB \- \- persona_mmap_page_zero\fR
personality(MMAP_PAGE_ZERO)
.TP
\fB \- \- persona_read_implies_exec\fR
personality(READ_IMPLIES_EXEC)
.TP
\fB \- \- persona_addr_limit_3gb\fR
personality(ADDR_LIMIT_3GB)
.TP
\fB \- \- persona_addr_no_randomize\fR
personality(ADDR_NO_RANDOMIZE)
.TP
\fB \- \- disable_clone_newnet\fR |\- N
2018-06-13 05:27:31 +08:00
Don't use CLONE_NEWNET. Enable global networking inside the jail
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- disable_clone_newuser\fR
Don't use CLONE_NEWUSER. Requires euid==0
.TP
\fB \- \- disable_clone_newns\fR
Don't use CLONE_NEWNS
.TP
\fB \- \- disable_clone_newpid\fR
Don't use CLONE_NEWPID
.TP
\fB \- \- disable_clone_newipc\fR
Don't use CLONE_NEWIPC
.TP
\fB \- \- disable_clone_newuts\fR
Don't use CLONE_NEWUTS
.TP
2017-10-27 12:25:59 +08:00
\fB \- \- disable_clone_newcgroup\fR
Don't use CLONE_NEWCGROUP. Might be required for kernel versions < 4.6
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- uid_mapping\fR |\fB \- U\fR VALUE
2018-06-13 05:27:31 +08:00
Add a custom uid mapping of the form inside_uid:outside_uid:count. Setting this requires newuidmap (set-uid) to be present
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- gid_mapping\fR |\fB \- G\fR VALUE
2018-06-13 05:27:31 +08:00
Add a custom gid mapping of the form inside_gid:outside_gid:count. Setting this requires newgidmap (set-uid) to be present
2017-08-20 08:10:56 +08:00
.TP
\fB \- \- bindmount_ro\fR |\fB \- R\fR VALUE
List of mountpoints to be mounted \fB \- \- bind\fR (ro) inside the container. Can be specified multiple times. Supports 'source' syntax, or 'source:dest'
.TP
\fB \- \- bindmount\fR |\fB \- B\fR VALUE
List of mountpoints to be mounted \fB \- \- bind\fR (rw) inside the container. Can be specified multiple times. Supports 'source' syntax, or 'source:dest'
.TP
\fB \- \- tmpfsmount\fR |\fB \- T\fR VALUE
2018-06-13 05:27:31 +08:00
List of mountpoints to be mounted as tmpfs (R/W) inside the container. Can be specified multiple times. Supports 'dest' syntax. Alternatively, use '-m none:dest:tmpfs:size=8388608'
2017-08-20 08:10:56 +08:00
.TP
2018-02-24 15:39:36 +08:00
\fB \- \- mount\fR |\fB \- m\fR VALUE
Arbitrary mount, format src:dst:fs_type:options
.TP
2018-06-13 05:27:31 +08:00
\fB \- \- symlink\fR |\f \B \- s\fR VALUE
Symlink, format src:dst
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- disable_proc\fR
2018-06-13 05:27:31 +08:00
Disable mounting procfs in the jail
2017-08-20 08:10:56 +08:00
.TP
2017-10-12 14:53:10 +08:00
\fB \- \- proc_path\fR VALUE
Path used to mount procfs (default: '/proc')
.TP
\fB \- \- proc_rw\fR
2018-06-13 05:27:31 +08:00
Is procfs mounted as R/W (default: R/O)
2017-10-12 14:53:10 +08:00
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- seccomp_policy\fR |\fB \- P\fR VALUE
Path to file containing seccomp\- bpf policy (see kafel/)
.TP
\fB \- \- seccomp_string\fR VALUE
String with kafel seccomp\- bpf policy (see kafel/)
.TP
2018-05-24 08:44:31 +08:00
\fB \- \- seccomp_log\fR
2018-05-24 21:34:16 +08:00
Use SECCOMP_FILTER_FLAG_LOG. Log all actions except SECCOMP_RET_ALLOW. Supported since kernel version 4.14
2018-05-24 08:44:31 +08:00
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- cgroup_mem_max\fR VALUE
Maximum number of bytes to use in the group (default: '0' \- disabled)
.TP
2021-09-16 07:37:10 +08:00
\fB \- \- cgroup_mem_memsw_max\fR VALUE
Maximum number of memory+Swap bytes to use in the group (default: '0' \- disabled)
.TP
2021-10-29 12:14:45 +08:00
\fB \- \- cgroup_mem_swap_max\fR VALUE
Maximum number of swap bytes to use in the group (default: '-1' \- disabled)
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- cgroup_mem_mount\fR VALUE
Location of memory cgroup FS (default: '/sys/fs/cgroup/memory')
.TP
\fB \- \- cgroup_mem_parent\fR VALUE
Which pre\- existing memory cgroup to use as a parent (default: 'NSJAIL')
.TP
\fB \- \- cgroup_pids_max\fR VALUE
Maximum number of pids in a cgroup (default: '0' \- disabled)
.TP
\fB \- \- cgroup_pids_mount\fR VALUE
Location of pids cgroup FS (default: '/sys/fs/cgroup/pids')
.TP
\fB \- \- cgroup_pids_parent\fR VALUE
Which pre\- existing pids cgroup to use as a parent (default: 'NSJAIL')
.TP
2017-10-25 16:56:14 +08:00
\fB \- \- cgroup_net_cls_classid\fR VALUE
Class identifier of network packets in the group (default: '0' \- disabled)
.TP
\fB \- \- cgroup_net_cls_mount\fR VALUE
Location of net_cls cgroup FS (default: '/sys/fs/cgroup/net_cls')
.TP
\fB \- \- cgroup_net_cls_parent\fR VALUE
Which pre\- existing net_cls cgroup to use as a parent (default: 'NSJAIL')
.TP
2018-02-24 15:39:36 +08:00
\fB \- \- cgroup_cpu_ms_per_sec\fR VALUE
2018-12-05 21:35:16 +08:00
Number of milliseconds of CPU time per second that the process group can use (default: '0' - no limit)
2018-02-24 15:39:36 +08:00
.TP
2018-06-13 05:27:31 +08:00
\fB \- \- cgroup_cpu_mount\fR VALUE
2018-02-24 15:39:36 +08:00
Location of cpu cgroup FS (default: '/sys/fs/cgroup/net_cls')
.TP
2018-06-13 05:27:31 +08:00
\fB \- \- cgroup_cpu_parent\fR VALUE
2018-02-24 15:39:36 +08:00
Which pre-existing cpu cgroup to use as a parent (default: 'NSJAIL')
.TP
2019-07-26 22:02:17 +08:00
\fB \- \- cgroupv2_mount\fR VALUE
Location of cgroup v2 directory (default: '/sys/fs/cgroup')
.TP
\fB \- \- use_cgroupv2\fR
Use cgroup v2
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- iface_no_lo\fR
2018-06-13 05:27:31 +08:00
Don't bring the 'lo' interface up
2017-08-20 08:10:56 +08:00
.TP
2018-06-02 23:02:09 +08:00
\fB \- \- iface_own\fR VALUE
Move this existing network interface into the new NET namespace. Can be specified multiple times
.TP
2017-08-20 08:10:56 +08:00
\fB \- \- macvlan_iface\fR |\fB \- I\fR VALUE
Interface which will be cloned (MACVLAN) and put inside the subprocess' namespace as 'vs'
.TP
\fB \- \- macvlan_vs_ip\fR VALUE
IP of the 'vs' interface (e.g. "192.168.0.1")
.TP
\fB \- \- macvlan_vs_nm\fR VALUE
Netmask of the 'vs' interface (e.g. "255.255.255.0")
.TP
\fB \- \- macvlan_vs_gw\fR VALUE
Default GW for the 'vs' interface (e.g. "192.168.0.1")
2018-10-23 21:05:50 +08:00
.TP
\fB \- \- macvlan_vs_ma\fR VALUE
2018-10-24 04:24:43 +08:00
MAC-address of the 'vs' interface (e.g. "ba:ad:ba:be:45:00")
2017-08-20 08:10:56 +08:00
\"
.SH Examples
.PP
Wait on a port 31337 for connections, and run /bin/sh:
.IP
nsjail \- Ml \- \- port 31337 \- \- chroot / \- \- /bin/sh \- i
.PP
Re\- run echo command as a sub\- process:
.IP
nsjail \- Mr \- \- chroot / \- \- /bin/echo "ABC"
.PP
Run echo command once only, as a sub\- process:
.IP
nsjail \- Mo \- \- chroot / \- \- /bin/echo "ABC"
.PP
Execute echo command directly, without a supervising process:
.IP
nsjail \- Me \- \- chroot / \- \- disable_proc \- \- /bin/echo "ABC"
\"