Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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 na-
	      tive 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  ad-
	      dresses  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  ad-
	      dress 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  en-
	      crypted)
	       - 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	jadm

SEE ALSO
       jail(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 re-
       port to jadm@dachev.info

AUTHOR
       Nikolay Georgiev	Dachev (nikolay@dachev.info)

1.0				  09 Sep 2014				man(8)

NAME | DESCRIPTION | REQUIREMENTS | OPTIONS | SEE ALSO | BUGS | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=jadm&sektion=8&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help