Differential D20967 Diff 60618 share/man/man4/mac_ipacl.4

Changeset View

Standalone View

View Options

share/man/man4/mac_ipacl.4

This file was added.

.\"

.\" This code was developed as a Google Summer of Code 2019 project

.\" under the guidance of Bjoern A. Zeeb.

.\"

.\" Redistribution and use in source and binary forms, with or without

.\" modification, are permitted provided that the following conditions

.\" are met:

.\" 1. Redistributions of source code must retain the above copyright

.\" notice, this list of conditions and the following disclaimer.

.\" 2. Redistributions in binary form must reproduce the above copyright

.\" notice, this list of conditions and the following disclaimer in the

.\" documentation and/or other materials provided with the distribution.

.\"

.\" THIS SOFTWARE IS PROVIDED BY THE AUTHORS AND CONTRIBUTORS ``AS IS'' AND

.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE

.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE

.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE

.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL

.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS

.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)

.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT

.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY

.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

.\" SUCH DAMAGE.

.\"

.\" $FreeBSD$

.\"

.Dd August 10, 2019

.Dt MAC_IPACL 4

.Os

.Sh NAME

.Nm mac_ipacl

.Nd "IP Address access control policy"

.Sh SYNOPSIS

Add the following lines in your kernel configuration file for compiling the

IP address access control policy into your kernel:

dchUnsubmitted

Done

s/for compiling/to compile/

dch: s/for compiling/to compile/

.Bd -ragged -offset indent

.Cd "options MAC"

.Cd "options MAC_IPACL"

.Ed

.Pp

For loading the mac_ipacl policy module at boot time,

in your kernel configuration file add the following line:

dchUnsubmitted

Done

"To load the mac_ipacl policy module at boot time, add the following lien to your kernel configuration file" reads better.

dch: "To load the mac_ipacl policy module at boot time, add the following lien to your kernel…

.Bd -ragged -offset indent

.Cd "options MAC"

.Ed

.Pp

and in

.Xr loader.conf 5 add:

.Pp

.Dl "mac_ipacl_load=""YES"""

.Sh DESCRIPTION

The

.Nm

policy allows the root of the host to limit the

.Xr VNET 9

jail's privileges of setting IPv4 and IPv6 addresses via

.Xr sysctl 8

interface.

pauamma_gundo.comUnsubmitted

Done

.Sh DESCRIPTION

The

.Nm

- policy allows the root of the host to limit the

- .Xr VNET 9

- jail's privileges of setting IPv4 and IPv6 addresses via

+ policy allows the root of the host to use the

.Xr sysctl 8

- interface.

+ interface to limit the

+ .Xr VNET 9

+ jail's ability to set IPv4 and IPv6 addresses.

So, the host can

Otherwise it looks like "via sysctl(8) interface" applies to "setting IPv4 and IPv6 addresses". (While there, tweak wording a bit.)

pauamma_gundo.com: Otherwise it looks like "via sysctl(8) interface" applies to "setting IPv4 and IPv6 addresses".

So, the host can

define rules for jails and their interfaces about IP addresses

with

.Xr sysctl 8

MIBs.

.Pp

Its default behaviour is to deny all IP addresses for the jail if

.Nm

pauamma_gundo.comUnsubmitted

Done

MIBs.

.Pp

- Its default behaviour is to deny all IP addresses for the jail if

+ Its default behavior is to deny all IP addresses for the jail if

.Nm

policy is enforced and allow/deny IP (or subnets) according to the

Missed that the first time: US spelling.

pauamma_gundo.com: Missed that the first time: US spelling.

policy is enforced and allow/deny IP(or subnets) according to

pauamma_gundo.comUnsubmitted

Done

Its default behaviour is to deny all IP addresses for the jail if

.Nm

- policy is enforced and allow/deny IP(or subnets) according to

+ policy is enforced and allow/deny IP (or subnets) according to the

.Va security.mac.ipacl.rules

pauamma_gundo.com:

.Va security.mac.ipacl.rules

string specified with

.Xr sysctl 8

.Ss Runtime Configuration

The following

.Xr sysctl 8

MIBs are used to control enforcement and behavior of this MAC Policy.

.Bl -tag -width indent

.It Va security.mac.ipacl.ipv4

Enforce

.Nm

for IPv4 addresses.

(Default: 1).

.It Va security.mac.ipacl.ipv6

Enforce

.Nm

for IPv6 addresses.

(Default: 1).

.It Va security.mac.ipacl.rules

The IP address access control list is specified in the following format:

.Pp

0mpUnsubmitted

Done

POlicy is a typo, right?

0mp: //POlicy// is a typo, right?

.Sm off

.D1 jid @ allow @ interface @ addr_family @ IP_addr @ prefix Op , jid @ ...

.Sm on

.Bl -tag -width "interface"

.It jid

Describe the jail id of the jail for which the rule is written.

.It allow

dchUnsubmitted

Done

is it possible to set the jail id to * such that it applies to *all* jails?

The jid is not necessarily known in advance of jail creation, which makes assigning them in a static config more tricky.

No need to change the code today, but this would be a great future enhancement. As you note further down in the manpage, a better way of setting this would be nice. Perhaps these can be attached somehow at jail creation.

dch: is it possible to set the jail id to * such that it applies to *all* jails? The jid is not…

shivankAuthorUnsubmitted

Done

It's a good suggestion to use a jail wildcard, like we did for Interface.
will consider it as future enhancement.

shivank: It's a good suggestion to use a jail wildcard, like we did for Interface. will consider it as…

1 for allow and 0 for deny.

Decides action performed for the rule.

.It interface

Name of the interface the rule is enforced for.

If the Interface is left empty then it is a wildcard to enforce the

pauamma_gundo.comUnsubmitted

Done

Name of the interface the rule is enforced for.

- If the Interface is left empty then it is a wildcard to enforce the

+ If the interface is left empty then it is a wildcard to enforce the

rule for all interfaces.

pauamma_gundo.com:

rule for all interfaces.

.It addr_family

Address family of the IP_addr.

The input to be given as AF_INET or AF_INET6

string only.

.It IP_addr

0mpUnsubmitted

Done

.Ar is not needed as macros are not expanded here.

0mp: `.Ar` is not needed as macros are not expanded here.

IP address(or subnet) to be allowed/deny.

pauamma_gundo.comUnsubmitted

Done

.It IP_addr

- IP address(or subnet) to be allowed/deny.

+ IP address (or subnet) to be allowed/denied.

Action depends on the prefix length.

pauamma_gundo.com:

Action depends on the prefix length.

.It prefix

Prefix length of the subnet to be enforced by the policy.

-1 implies the policy is enforced for individual IP address.

pauamma_gundo.comUnsubmitted

Done

Prefix length of the subnet to be enforced by the policy.

- -1 implies the policy is enforced for individual IP address.

+ -1 implies the policy is enforced for the individual IP address.

For non-negative value, a range of IP address (present in subnet)

pauamma_gundo.com:

For non-negative value, a range of IP address (present in subnet)

pauamma_gundo.comUnsubmitted

Done

-1 implies the policy is enforced for individual IP address.

- For non-negative value, a range of IP address (present in subnet)

+ For a non-negative value, a range of IP addresses (present in subnet)

which is calculated as subnet = IP_addr & mask.

pauamma_gundo.com:

which is calculated as subnet = IP_addr & mask.

.El

.Sh EXAMPLES

Behavior of the

.Nm

policy module for different inputs of sysctl variable:

.Bl -tag -width "1."

.It 1.

Assign ipv4=1, ipv6=0 and rules="1@1@@AF_INET@169.254.123.123@-1"

.Pp

It allow only 169.254.123.123 IPv4 address for all interfaces (wildcard) of jail 1.

It allow all IPv6 address since the policy is not enforced for IPv6.

pauamma_gundo.comUnsubmitted

Done

It allow only 169.254.123.123 IPv4 address for all interfaces (wildcard) of jail 1.

- It allow all IPv6 address since the policy is not enforced for IPv6.

+ It allows all IPv6 addresses since the policy is not enforced for IPv6.

.It 2.

pauamma_gundo.com:

.It 2.

0mpUnsubmitted

Done

Please start new sentences in a new line.

0mp: Please start new sentences in a new line.

Assign ipv4=1, ipv6=1 and rules="1@1@epair0b@AF_INET6@fe80::@32,1@0@epair0b@AF_INET6@fe80::abcd@-1"

.Pp

It deny all IPv4 address as the policy is enforced but no rules are specified

0mpUnsubmitted

Done

Missing space before (.

0mp: Missing space before `(`.

pauamma_gundo.comUnsubmitted

Done

Assign ipv4=1, ipv6=1 and rules="1@1@epair0b@AF_INET6@fe80::@32,1@0@epair0b@AF_INET6@fe80::abcd@-1"

.Pp

- It deny all IPv4 address as the policy is enforced but no rules are specified

+ It denies all IPv4 addresses as the policy is enforced but no rules are specified

about it.

pauamma_gundo.com:

about it.

It allow all IPv6 address in the subnet- fe80::/32 except

pauamma_gundo.comUnsubmitted

Done

about it.

- It allow all IPv6 address in the subnet- fe80::/32 except

+ It allows all IPv6 addresses in subnet fe80::/32 except

fe80::abcd for interface epair0b only.

pauamma_gundo.com:

fe80::abcd for interface epair0b only.

.It 3.

Assign ipv4=1, ipv6=1, rules="2@1@@AF_INET6@fc00::@7,2@0@@AF_INET6@fc00::1111:2200@120,2@1@@AF_INET6@fc00::1111:2299@-1,1@1@@AF_INET@198.51.100.0@24"

.Pp

It allow IPv4 in the subnet 198.51.100.0/24 for jail 2 and

pauamma_gundo.comUnsubmitted

Done

Assign ipv4=1, ipv6=1, rules="2@1@@AF_INET6@fc00::@7,2@0@@AF_INET6@fc00::1111:2200@120,2@1@@AF_INET6@fc00::1111:2299@-1,1@1@@AF_INET@198.51.100.0@24"

.Pp

- It allow IPv4 in the subnet 198.51.100.0/24 for jail 2 and

+ It allows IPv4 in subnet 198.51.100.0/24 for jail 2 and

all interfaces.

pauamma_gundo.com:

all interfaces.

It allow IPv6 address in the subnet fc00::/7 but

deny the subnet fc00::1111:2200/120, and allow individual IP

fc00::1111:2299 from the denied subnet for all interfaces in jail 2.

pauamma_gundo.comUnsubmitted

Done

all interfaces.

- It allow IPv6 address in the subnet fc00::/7 but

- deny the subnet fc00::1111:2200/120, and allow individual IP

+ It allows IPv6 addresses in subnet fc00::/7 but

+ denies subnet fc00::1111:2200/120, and allows individual IP

fc00::1111:2299 from the denied subnet for all interfaces in jail 2.

.El

Please refer to mac/ipacl tests-framework for wide variety of examples on using

pauamma_gundo.com:

.El

Please refer to mac/ipacl tests-framework for wide variety of examples on using

the ipacl module.

.Sh LIMITATIONS/PRECAUTIONS

Rules are checked in the same sequence they are given.

If many rules are there for an IP address (or a set of IP addresses),

the result depends on final rule.

.Sh FUTURE WORKS

dchUnsubmitted

Done

I think this should be more clear -

is this, if an IP address, (or subnet), is mentioned repeatedly, *only* the final rule is applied? i.e. all previous ones are ignored?
or are they somehow cumulative, in order, with the last one potentially overriding?

dch: I think this should be more clear - - is this, if an IP address, (or subnet), is mentioned…

shivankAuthorUnsubmitted

Done

rephrased.

shivank: rephrased.

Rules are given with sysctl interface which gets very complex to give them

all in command line.

It has to be simplified with a better way to input those rules.

.Sh SEE ALSO

.Xr mac 4 ,

.Xr mac 9

.Sh AUTHORS

The

.Nm

policy module was developed as a Google Summer of Code Project in 2019

.An -nosplit

.An "Shivank Garg" Aq Mt shivank@FreeBSD.org

under the guidance of

.An "Bjoern A. Zeeb" Aq Mt bz@FreeBSD.org .

0mpUnsubmitted

Done

missing a space before (

0mp: missing a space before `(`