man(8)jadm man page man(8)NAME
JADM (jail admin) - FreeBSD jail framework with vnet, zfs and
/etc/jail.conf support
DESCRIPTION
Jadm is python script which pars /etc/jail.conf in his own format. Jadm
use zfs for jail home also bridge interface and epair interfaces for
jail vnet.
Jadm can manage four different types of jails
vnet
Jadm use bridge interface with epair interfaces, also jid is
used for epair interface number. Bridge interface should contain
at leas one ip address which will be used for vnet-jail gateway.
We can use multiple (alias) ip addresses from different net‐
works.
ip address from host system
Can be used any already assigned ip address of system interfaces
BASE (skeleton model)
When we need BASE skeleton model, first we should create jail
called 'BASE' with jadm create command. When 'BASE' jail is cre‐
ated jadm will create 3 different zfs folders.
./BASE/
This folder content jail base files which will be used for
all BASE-jails. Mounted under / inside BASE-jail with (RO), only
jail with name 'BASE-update' is mounted with (RW).
Can be installed via (BSD, SRC or Template)
./BASE-SKELETON/
This folder is the install template for new BASE-jail (RW)
./BASE-RW/
This folder content (RW) BASE-jail and is main for jail, zfs
quota apply to this folder.
./BASE-jailname/
This empty folder is used for mount point of:
./BASE/ mounted to ./BASE-jailname/ (RO)
./BASE-RW/BASE-jailname/ ./BASE-jailname/SROOT/ (RW)
To update 'BASE' and all 'BASE-' jails, create jail called
'BASE-update' which will have 'BASE' (RW) mounted or /etc/fstab
can be changed for any BASE-jail.
When create new jail enter only a jail name, if (skel) install
source is used jadm will add 'BASE-' automatically in the name.
normal jail
Normal jails are regular jail which can be installed via BSD -
bsd installer, SRC - builded/pre-builded freebsd /usr/src or
templates.
Templates
Every existing jail can be used as template. Vnet jail cannot be
used as a template for NoVnet jail and vice versa. Jadm will
create the new jail from the same type (BASE or normal)
When template is used jadm create zfs snapshot and send/restore
it to new jail home. This require additional free space but we
avoid zfs clone dependency. Also jadm copy all jail local set‐
tings from the template jail.
/etc/jail.conf example
Every jail created with jadm can be managed and with freebsd
native tools.
Jails Global Settings are common for all jails, local settings
are only for their jail also they override global settings.
Please do not change comments '#' in jail.conf if is used by jadm.
(This is jadm settings section please do not edit it manually if
you don't know what to do)
######## JADM ver. 1.0 Settings ########
# DO NOT CHANGE THIS SECTION OR COMENTS WITH "@"
$jzfs = "zroot/jails";
$jedir = "/jails/";
$bridge = "bridge1";
$epair = "epair$jid";
$a = "a";
$b = "b";
(Jadm generate random mac address for each new epair'b' inter‐
face on each jail start. 'ifconfig create' don't know (but Free‐
BSD kernel know) mac addresses for previously created epair'b'
interfaces after we move them in vnet - network stack.)
$newmac = "dd if=/dev/urandom bs=1024 count=1
2>/dev/null|md5|sed
's/^\(..\)\(..\)\(..\).*$/02\:ff\:c0\:\1:\2:\3/'";
path = "$jedir$name";
(Those settings apply to all jails)
#@### Jails Global Settings #####
allow.raw_sockets;
#@###### Jails Settings ########
(This is 'BASE' jail - do not change)
BASE
{
# created on 2014-09-04 18:39:38.565545 by ... JADM ...
host.hostname = BASE.localhost;
jid = 0;
$jip = "0.0.0.0";
$jgw = "0.0.0.0";
### local settings ###
}
vnet
{
(jadm info comment - do not change)
# modified on 2014-09-04 20:45:43.980510 by ... JADM ...
host.hostname = test;
jid = 5;
$jip = "10.10.50.50/24";
$jgw = "10.10.50.1";
(vnet-jail network config - do not change)
### network settings ###
vnet;
vnet.interface = "$epair$b";
exec.start = "ifconfig lo0 127.0.0.1/8";
exec.prestart = "ifconfig $epair create";
exec.prestart += "$newmac |xargs ifconfig $epair$b ether";
exec.prestart += "ifconfig $bridge addm $epair$a up";
exec.prestart += "ifconfig $epair$a up";
exec.start += "ifconfig $epair$b $jip";
exec.start += "route add default $jgw";
exec.start += "/bin/sh /etc/rc";
exec.poststop = "ifconfig $bridge deletem $epair$a";
exec.poststop += "ifconfig $epair$a destroy";
exec.stop = "/bin/sh /etc/rc.shutdown";
exec.clean;
persist;
### local settings ###
devfs_ruleset=5;
}
BASE-novnet
{
# created on 2014-09-07 19:31:50.997155 by ... JADM ...
host.hostname = test-base.local.host;
jid = 12;
$jip = "1.2.3.4";
$jgw = "system";
### network settings ###
ip4.addr = "$jip";
exec.start = "/bin/sh /etc/rc";
exec.stop = "/bin/sh /etc/rc.shutdown";
persist;
(BASE skeleton jail mount settings - do not change)
### BASE mount settings ###
mount.fstab="/jails/BASE-RW/BASE-novnet/etc/fstab";
mount.devfs;
(jail local settings apply only for jail also replace global
settings - we can change)
### local settings ###
devfs_ruleset=4;
}
REQUIREMENTS
'options VIMAGE'
in FreeBSD custom kernel
already existing bridge interface with ip address
you can use multiple ip's which are used for jails gateways for
different network
OPTIONS
initsetup
select existing bridge interface as default and jails home zfs
(zpool should exist)
setup
change bridge interface (if you change it please change and
jails gatways/ip via modify option) and default jail home zfs
(jadm will rename all jails home path to new zfs home)
create
Jail Name:> this name will be used also and for jail zfs home
Hostname:> jail hostname example: jail.local.lan
Jail ID:> will be used and for jail epair inteface number (vnet
/ bridge interface conection)
Vnet support (y):> if (y) is selected jail will be created with
vnet support.
Gateway number:> if is (vnet) bridge interfaces assigned ip
addresses which are used for jail default gateway and jail net‐
work, just select a number.
Jail IP Address:> if is (vnet) jail ip address should be from
them same network with gateway ip, network mask will be added
automatically, if is not (vnet) you can enter any valid ip
address from the host system.
Jail ZFS Quota (M)egabytes, (G)igabytes, (none) for unlimited:>
enter zfs quota for jail or use 'none' (or leave it empty) if
quota is not needed example: 10G
install source:> jadm will ask how to install new jail
(template) use existing jail like a template - (vnet) jaill can‐
not be used as (novnet) jail and vice versa. All jail local set‐
tings will be copyed to new jail
(bsd) use bdsinstaller which is similiar to new freebsd instala‐
tion. During this process bsdinstaller will use internet to don‐
wload FreeBSD pkg's
(src) jadm will build jail environment from FreeBSD sources
/usr/src. You can make new buildworld or you can use already
builded. Ony bsd system envoirment will be installed evrething
else shold be installed manualy (like /usr/ports and etc.)
(skel) jail skeleton model 'BASE' jails
After all required data is entered jadm will show summarise config and
will ask for confirmation (y/n) In this stage jadm will create zfs path
for your jail if this zfs path already exist jadm will ask how to pro‐
ceed
(recreate) will destroy zfs path and existing data and will cre‐
ate new one with same name
(use) will use existing zfs path (jail environment) and will
complete installation
After jail installation, jadm will execute post install function with
default settings for jail /etc/rc.conf and /etc/resolv.conf
/etc/jail.conf
sendmail_enable="NONE"
firewall_enable="YES"
firewall_script="/etc/rc.firewall"
firewall_type="OPEN"
/etc/resolv.conf
nameserver 8.8.8.8
modify
modify existing jail (name, hostname, jid, gateway, ip addr and
zfs quota)
destroy
remove jail config from /etc/jail.conf and destroy jail zfs data
remove
remove jail config from /etc/jail.conf but will keep jail zfs
data
migrate
migrate jail from on host to other. Jadm will migrate jail con‐
fig via his own client/server. Jail zfs will be migrated via
ssh.
1. server/client comunicate with jadm socket server (AES
encrypted)
- password for AES encription must be exactly 16 symbols if not
jadm will add '0'
2. ssh public key for current user must be added to remote
user@server:~/.ssh/authorized_keys
- remote user should be able to use (sudo zfs receive), do not
use root!
- zfs pool will be transferd via ssh
3. start server on remote machine before client on local
server:
- migrate server (ip address: def *) (port: def 4555) (server
password)
client:
- migrate client (remote user@host/ip) (remote port: def 4555)
(server password) (jail name/id)
snap
Create/Restore from jail zfs snapshot
start, stop or reboot
jadm will skip all jails which include 'template' in their name
shell
Enter in jail. Jadm check for shell which is set for jail root
user in /etc/passwd and execute 'jexec jid shell'
local
Jails local settings
For local setting you can use any sysctl jail settings like
'mount.ftab' and etc. Local setting apply only to jail.
global
Jails global settings
For global etting you can use any sysctl jail settings like
'mount.ftab' and etc. Global setting apply only to all jails.
gateways
List available Jail gateways on the system bridge interface
(vnet)
list or jls
List Jais by name, hostname, ipaddress, gateway, active, inac‐
tive (jls - short table)
about
show jadm version and license agreement
help
list available commands with "help" or detailed help with "help
cmd".
verbose
by default is off. Show detailed message when jail is started
log
add custom log messge in /var/log/jadm.log
quit or exit
exit from jadmSEE ALSOjail(8), jail.conf(5), zpool(8), zfs(8), ifconfig(8) and bridge(4)BUGS
If you find any bugs, or if you experience any crashes, please send
report to jadm@dachev.info
AUTHOR
Nikolay Georgiev Dachev (nikolay@dachev.info)
1.0 09 Sep 2014 man(8)
