# Jail manual page inconsistency?



## ShelLuser (Sep 1, 2013)

Hi gang!

With my Linux to FreeBSD migration project nearly finished I have a little time to spare today, so I decided to finally put /usr/src to some good use: Jails.

I started by studying the jail(8) manual page and then noticed something odd regarding the -c parameter 'Create a new jail.'. I quote:


```
-c      Create a new jail.  The jail jid and name parameters (if speci-
        fied) on the command line, or any jails must not refer to an
        existing jail.
```
Note the extra information: any jid or name parameter specified _must not refer to an existing jail_.

So far, so good. My assumption at this point is that this command creates a new jail. To me it would boil down to adding an entry in /etc/jails.conf.

Continuing reading you'll come across the definitions for jid and name (both used to identify a jail) and then the Examples section.

First of all the section 'Setting up a Jail directory tree' which clearly explains how to build the actual Jail environment. I prefer using buildworld instead of world because I can take things one step at a time. Also because that example was used in the Handbook.

'Configuring the Jail' also contains no surprises, just like the quote above already told us the `# jail -c` command used here does not specify an existing jid nor name parameter.

And then we come to 'Starting the Jail', this part confuses me.

First they tell you to create an entry in /etc/jail.conf which contains all the settings for the jail you're setting up (defining things like hostname, used IP address, etc.). In their example they used testjail as the name of the jail (this becomes clear when reading the jail.conf(5) manual page; an entry begins with the jail name, then all parameters are defined between the brackets).

And then they mention this:


```
Start the jail by running:

      jail -c testjail

A few warnings may be produced; however, it should all work properly.
```
But what ever happened to not specifying a name or JID which referred to an existing jail?

Now, looking at the SYNOPSIS section again it becomes a little bit more clear:


```
jail [-dhilqv] [-J jid_file] [-u username] [-U username] [-cmr]
          param=value ... [command=command ...]
     jail [-dqv] [-f conf_file] [-p limit] [-cmr] [jail]
     jail [-qv] [-f conf_file] [-rR] [* | jail ...]
     jail [-dhilqv] [-J jid_file] [-u username] [-U username] [-n jailname]
          [-s securelevel] [path hostname [ip[,...]] command ...]
```
The earlier statement obviously refers to the -n parameter (jailname) and perhaps the -J parameter (jid_file; although the manual page mentions simply jid such a parameter doesn't seem to exist).

But isn't it true that -c doesn't create a new jail but basically starts one?

It appears to me as if the manual page is contradicting itself a little when referring to creating and starting a jail. From what I've read and understand so far both actions are basically the same; starting a jail is equal to creating one.

But wouldn't it be a bit more logical (and easier to understand) to emphase a little more on this and then continue using one action description (either starting or creating) instead of using both?

Now, perhaps I'm simply being impatient. At the time of writing `# make buildworld` is still running and I can't wait to continue to the next steps. Even so, I'm curious what you guys think of this.


----------



## ShelLuser (Sep 5, 2013)

I've been working with jails a bit longer and come to conclude that although it can be confusing for people new to jails; in the end this is a non-issue. Because you're actually both creating as well as starting something, at the very least you create a specific entry:


```
root@smtp2:/home/peter # jls
   JID  IP Address      Hostname                      Path
root@smtp2:/home/peter # jail -c dogma
dogma: created
Setting hostname: dogma.local.
<CUT>
root@smtp2:/home/peter # jls
   JID  IP Address      Hostname                      Path
     3  192.168.0.1     dogma.local                   /usr/jails/dogma
```
Something was definitely created.

Hmm, I think I should rename that thing to dogma.central instead


----------

