Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

jail.8: document multiple vnet.interfaces #1529

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
+1 −0
Open

jail.8: document multiple vnet.interfaces #1529

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions usr.sbin/jail/jail.8
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -946,9 +946,10 @@
.It Va vnet.interface
A network interface to give to a vnet-enabled jail after is it created.
The interface will automatically be released when the jail is removed.
Multiple interfaces can be specified as a comma-separated list.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm, I don't think this is true? It doesn't work for me in a simple test.

# ifconfig epair create
epair10a
# jail -c name=test persist vnet vnet.interface="epair10a,epair10b"
ifconfig: interface epair10a,epair10b does not exist                                                                                                           
jail: /sbin/ifconfig epair10a,epair10b vnet test: failed
#

Specifying vnet.interface multiple times works though, so we can mention that instead.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It doesn't work for me in a simple test.

this is working for me:

uk-mth-1-core {
        host.hostname "uk-mth-1-core.inet.le-fay.org";
        vnet new;
        vnet.interface = vtnet0, epair0b;
        devfs_ruleset 6;
}

# jexec uk-mth-1-core netstat -in -f inet6 | egrep 'vtnet|epair'
vtnet0      - fe80::%vtnet0/64   fe80::5054:ff:febb:1750%vtnet0       62     -     -       64     -     -
vtnet0      - 2a00:1098:6b::/64  2a00:1098:6b::1                    4513     -     -     2219     -     -
epair0b     - fe80::%epair0b/64  fe80::1%epair0b                      22     -     -      300     -     -

Specifying vnet.interface multiple times works though, so we can mention that instead.

this did not work for me. only the last specified interface is added to the jail.

testing on amd64 with FreeBSD 15.0-CURRENT #2 lf/main-n269078-561fbdac790: Sun Nov 3 16:32:20 GMT 2024.

Copy link
Contributor Author

@concussious concussious Nov 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe Multiple interfaces can be specified with additional vfs.interface arguments, or with a comma then space separated list in jail.conf(5)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

example of a failed configuration with multiple vnet.interface:

uk-mth-1-core {
        host.hostname "uk-mth-1-core.inet.le-fay.org";
        vnet new;
        #vnet.interface = vtnet0, epair0b;
        vnet.interface vtnet0;
        vnet.interface epair0b;
        devfs_ruleset 6;
}

# jexec uk-mth-1-core netstat -in -f inet6 | egrep 'vtnet|epair'
epair0b     - fe80::%epair0b/64  fe80::1%epair0b        0     -     -        1     -     -

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok, this is a difference between command-line argument parsing and jail.conf parsing. jail.conf.5 says,

Other parameters may have more than one value.  A comma-separated list of
     values may be set in a single statement, or an existing parameter list
     may be appended to using “+=”:

           ip4.addr = 10.1.1.1, 10.1.1.2, 10.1.1.3;

           ip4.addr = 10.1.1.1;
           ip4.addr += 10.1.1.2;
           ip4.addr += 10.1.1.3;

so perhaps it would be enough for the vnet.interface description to note that more than one value is allowed? Similar to how ip4.addr is described as a list of addresses.

Copy link
Contributor Author

@concussious concussious Nov 15, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Multiple interfaces can be specified as a comma-separated list.
This option can be specified multiple times.

Am I understanding correctly?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@concussious i think in principal this change is correct but i wonder, if i'd read that earlier, it would have actually helped me. the issue here seems to be that jail(8) is documented the jail command line rather than the jail.conf(5) config file and "can be specified multiple times" has different meaning in each context.

(i cannot immediately come up with a better wording here, however.)

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, section 5 is supposed to document configuration file syntax, and section 8 is supposed to document administration command line syntax.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Doc is a hard problem to be sure. The minimum bar is kind of that we need to be so good as to make it seem easy.

.It Va zfs.dataset
A list of ZFS datasets to be attached to the jail.
This requires

Check warning on line 952 in usr.sbin/jail/jail.8

View workflow job for this annotation

GitHub Actions / Style Checker 

Missing Signed-off-by: line

Check warning on line 952 in usr.sbin/jail/jail.8

View workflow job for this annotation

GitHub Actions / Style Checker 

Missing Signed-off-by: line
.Va allow.mount.zfs
to be set.
See
Expand Down