.TH "netlabelctl" 8 "31 May 2013" "paul@paul-moore.com" "NetLabel Documentation"

.\" //////////////////////////////////////////////////////////////////////////

.SH NAME

.\" //////////////////////////////////////////////////////////////////////////

netlabelctl \- NetLabel management utility

.\" //////////////////////////////////////////////////////////////////////////

.SH SYNOPSIS

.\" //////////////////////////////////////////////////////////////////////////

.B netlabelctl

[<global_flags>] <module> [<module_commands>]

.\" //////////////////////////////////////////////////////////////////////////

.SH DESCRIPTION

.\" //////////////////////////////////////////////////////////////////////////

.P

The NetLabel management utility, netlabelctl, is a command line program

designed to allow system administrators to configure the NetLabel system in the

kernel.  The utility is based around different "modules" which correspond to

the different types of NetLabel commands supported by the kernel.

.\" //////////////////////////////////////////////////////////////////////////

.SH OPTIONS

.\" //////////////////////////////////////////////////////////////////////////

.SS Global Flags

.TP 5

.B \-h

Help message

.TP 5

.B \-p

Attempt to make the output human readable or "pretty"

.TP 5

.B \-t <seconds>

Set a timeout to be used when waiting for the NetLabel subsystem to respond

.TP 5

.B \-v

Enable extra output

.TP 5

.B \-V

Display the version information

.\" //////////////////////////////////////////////////////////////////////////

.SS Modules and Commands

.TP 5

.B mgmt

.P

The management module is used to perform general queries about the NetLabel

subsystem within the kernel.  The different commands and their syntax are

listed below.

.HP

.I version

.br

Display the kernel's NetLabel management protocol version.

.HP

.I protocols

.br

Display the kernel's list of supported labeling protocols.

.TP 5

.B map

.P

The domain mapping module is used to map different NetLabel labeling protocols

to either individual LSM domains or the default domain mapping.  It is up to

each LSM to determine what defines a domain.  With SELinux, the normal SELinux

domain should be used, i.e. "ping_t".  In addition to protocol selection based

only on the LSM domain, it is also possible to select the labeling protocol

based on both the LSM domain and destination address.  The network address

selectors can specify either single hosts or entire networks and work for both

IPv4 and IPv6, although the labeling protocol chosen must support the IP

version chosen.  When specifying the labeling protocol to use for each mapping

there is an optional "extra" field which is used to further identify the

specific labeling protocol configuration.  When specifying the unlabeled

protocol, "unlbl", an extra value of either "4" or "6" may be used.  This

restricts the mapping to IPv4 or IPv6 addresses.  Omitting the extra value will

result in a mapping for all address families.  When specifying the CIPSO/IPv4

or the CALIPSO/IPv6 protocol, "cipso" or "calipso", the DOI value should be

specified; see the EXAMPLES section for details.  The different commands and their

syntax are listed below.

.HP

.I add default|domain:<domain> [address:<ADDR>[/<MASK>]] protocol:<protocol>[,<extra>]

.br

Add a new LSM domain / network address to NetLabel protocol mapping.

.HP

.I del default|domain:<domain>

.br

Delete an existing LSM domain to NetLabel protocol mapping.

.HP

.I list

.br

Display all of the configured LSM domain to NetLabel protocol mappings.

.TP 5

.B unlbl

.P

The unlabeled (unlbl) module controls the unlabeled protocol which is used both

when labeling outgoing traffic is not desired as well as when unlabeled

traffic is received by the system.  This module allows administrators to block

all unlabeled packets from the system through the "accept" flag and assign

static, or fallback, security labels to unlabeled traffic based on the inbound

network interface and source address.

.HP

.I accept on|off

.br

Toggle the unlabeled traffic accept flag.

.HP

.I add default|interface:<dev> address:<addr>[/<mask>] label:<label>

.br

Add a new static/fallback entry.

.HP

.I del default|interface:<dev> address:<addr>[/<mask>]

.br

Delete an existing static/fallback entry.

.HP

.I list

.br

Display the status of the unlabeled accept flag.

.TP 5

.B cipso

.P

The CIPSO/IPv4 (cipso) module controls the CIPSO/IPv4 labeling engine in the

kernel.  The CIPSO/IPv4 engine provided by NetLabel supports multiple Domains

Of Interpretation (DOI) and the CIPSO/IPv4 module allows for different

configurations for each DOI.  At present there are three types of 

configurations, the "trans" configuration which allows on\-the\-fly translation

of MLS sensitivity labels, the "pass" configuration which does not perform any

translation of the MLS sensitivity label and the "local" configuration which

conveys the full LSM security label over localhost/loopback connections.

Regardless of which configuration type is chosen a DOI value must be specified

and if the "trans" or "pass" configurations are specified then a list of the

CIPSO/IPv4 tag types to use when generating the CIPSO/IPv4 packet labels must

also be specified.  The list of CIPSO/IPv4 tags is ordered such that when

possible the first tag type listed is used when a CIPSO/IPv4 label is generated.

However, if it is not possible to use the first tag type then each tag type is

checked, in order, until a suitable tag type is found.  If a valid tag type can

not be found then the operation causing the CIPSO/IPv4 label will fail,

typically this occurs whenever a new socket is created.  The different commands

and their syntax are listed below.

.HP

.I add trans doi:<DOI> tags:<T1>,<Tn> levels:<LL1>=<RL1>,<LLn>=<RLn> categories:<LC1>=<RC1>,<LCn>=<RCn>

.br

Add a new CIPSO/IPv4 configuration using the standard/translated mapping with

the given level and category translations.  The levels are translated in such a

way that the local level "LLn" is translated to the remote, on\-the\-wire level

of "RLn"; the reverse translation is done for incoming packets.  The same

translation is done for the categories using "LCn" and "RCn".  In order for a

packet to be accepted, or a socket created by an application, there must be a

translation for the sensitivity level and all the categories present in the MLS

sensitivity label; if the entire requested sensitivity label can not be

translated the application will fail.

.HP

.I add pass doi:<DOI> tags:<T1>,<Tn>

.br

Add a new CIPSO/IPv4 configuration without any level or category translations.

.HP

.I add local doi:<DOI>

.br

Add a new CIPSO/IPv4 configuration for localhost/loopback connections.

.HP

.I del doi:<DOI>

.br

Delete an existing CIPSO/IPv4 configuration with the given DOI value.  If any

LSM domain mappings are present which make use of this DOI they will also be

deleted.

.HP

.I list [doi:<DOI>]

.br

Display a list of all the CIPSO/IPv4 configurations or just the configuration

matching the optionally specified DOI.

.TP 5

.B calipso

.P

The CALIPSO/IPv6 (calipso) module controls the CALIPSO/IPv6 labeling engine in the

kernel.  This behaves in a very similar way to the CIPSO/IPv4 engine, however the

protocol only specifies one tag-type (equivalent to CIPSO tag-type 1) and so the

tag-type should not be specified.  In addition there is no support for the "local"

or "trans" configuration.  The different commands and their syntax are listed below.

.HP

.I add pass doi:<DOI>

.br

Add a new CALIPSO/IPv6 configuration without any level or category translations.

.HP

.I del doi:<DOI>

.br

Delete an existing CALIPSO/IPv6 configuration with the given DOI value.  If any

LSM domain mappings are present which make use of this DOI they will also be

deleted.

.HP

.I list [doi:<DOI>]

.br

Display a list of all the CALIPSO/IPv6 configurations or just the configuration

matching the optionally specified DOI.

.\" //////////////////////////////////////////////////////////////////////////

.SH EXIT STATUS

.\" //////////////////////////////////////////////////////////////////////////

Returns zero on success, errno values on failure.

.\" //////////////////////////////////////////////////////////////////////////

.SH "EXAMPLES"

.\" //////////////////////////////////////////////////////////////////////////

.TP 5

.I netlabelctl cipso add pass doi:16 tags:1

.br

Add a CIPSO/IPv4 configuration with a DOI value of "16", using CIPSO tag "1"

(the permissive bitmap tag).  The CIPSO and LSM levels/categories are passed

through the NetLabel subsystem without any translation.

.HP

.I netlabelctl cipso add trans doi:8 tags:1 levels:0=0,1=1 categories:0=1,1=0

.br

Add a CIPSO/IPv4 configuration with a DOI value of "8", using CIPSO tag "1"

(the permissive bitmap tag).  The specified mapping converts local LSM levels

"0" and "1" to CIPSO levels "0" and "1" respectively while local LSM categories

"0" and "1" are mapped to CIPSO categories "1" and "0" respectively.

.HP

.I netlabelctl \-p cipso list

.br

Display all of the CIPSO/IPv4 configurations in a human readable format.

.HP

.I netlabelctl \-p cipso list doi:16

.br

Display specific information about the CIPSO/IPv4 DOI 16 configuration.

.HP

.I netlabelctl cipso del doi:8

.br

Delete the CIPSO/IPv4 configuration assigned to DOI 8.  In addition to

removing the CIPSO/IPv4 configuration any domain mappings using this

configuration will also be removed.

.HP

.I netlabelctl map add domain:lsm_domain protocol:cipso,8

.br

Add a domain mapping so that all outgoing packets sent from the "lsm_domain"

will be labeled according to the CIPSO/IPv4 protocol using DOI 8.

.HP

.I netlabelctl map add domain:lsm_domain address:192.168.1.0/24 protocol:cipso,8

.br

Add a mapping so that all outgoing packets sent from the "lsm_domain" to the

192.168.1.0/24 network will be labeled according to the CIPSO/IPv4 protocol

using DOI 8.

.HP

.I netlabelctl \-p map list

.br

Display all of the domain mappings in a human readable format.

.HP

.I netlabelctl del domain:lsm_domain

.br

Delete the domain mapping for the "lsm_domain", packets sent from the

"lsm_domain" will fallback to the default NetLabel mapping.

.HP

.I netlabelctl unlbl add interface:lo address:::1 label:foo

.br

Add a static/fallback label to assign the "foo" security label to unlabeled

packets entering the system over the "lo" (loopback) interface with an IPv6

source address of "::1" (localhost).

.HP

.I netlabelctl unlbl add default address:192.168.0.0/16 label:bar

.br

Add a static/fallback label to assign the "bar" security label to unlabeled

packets entering the system over any interface with an IPv4 source address in

the 192.168.0.0/16 network.

.\" //////////////////////////////////////////////////////////////////////////

.SH "NOTES"

.\" //////////////////////////////////////////////////////////////////////////

.P

The NetLabel subsystem is supported on Linux Kernels version 2.6.19 and later.

The static, or fallback, labels are only supported on Linux Kernels version

2.6.25 and later.  The domain mapping address selectors are only supported on

Linux Kernels 2.6.28 and later and CALIPSO/RFC5570 is only supported on Linux

Kernels 4.8.0 and later.

.P

The NetLabel project site, with more information including the source code

repository, can be found at https://github.com/netlabel.  Please report any

bugs at the project site or directly to the author.

.\" //////////////////////////////////////////////////////////////////////////

.SH "AUTHOR"

.\" //////////////////////////////////////////////////////////////////////////

Paul Moore <paul@paul-moore.com>

.\" //////////////////////////////////////////////////////////////////////////

.SH "SEE ALSO"

.\" //////////////////////////////////////////////////////////////////////////

.BR netlabel-config (8)