npf/npfctl/npfctl.8

.\"	$NetBSD: npfctl.8,v 1.25 2020/05/30 14:16:56 rmind Exp $
.\"
.\" Copyright (c) 2009-2014 The NetBSD Foundation, Inc.
.\" All rights reserved.
.\"
.\" This material is based upon work partially supported by The
.\" NetBSD Foundation under a contract with Mindaugas Rasiukevicius.
.\"
.\" 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 NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
.\"
.Dd May 12, 2020
.Dt NPFCTL 8
.Os
.Sh NAME
.Nm npfctl
.Nd control NPF packet filter
.Sh SYNOPSIS
.Nm npfctl
.Ar command
.Op Ar arguments
.\" -----
.Sh DESCRIPTION
The
.Nm
command can be used to control the NPF packet filter.
For a description of NPF's configuration file, see
.Xr npf.conf 5 .
.Pp
The first argument,
.Ar command ,
specifies the action to take.
Valid commands are:
.Bl -tag -width reload -offset 3n
.It Ic start
Enable packet inspection using the currently loaded configuration, if any.
Note that this command does not load or reload the configuration,
or affect existing connections.
.It Ic stop
Disable packet inspection.
This command does not change the currently loaded configuration,
or affect existing connections.
.It Ic reload Op Ar path
Load or reload configuration from file.
The configuration file at
.Pa /etc/npf.conf
will be used unless a file is specified by
.Ar path .
All connections will be preserved during the reload, except those which
will lose NAT policy due to removal.
NAT policy is determined by the translation type and address.
Note that change of filter criteria will not expire associated connections.
The reload operation (i.e., replacing the ruleset, NAT policies and tables)
is atomic.
.It Ic flush
Flush configuration.
That is, remove all rules, tables and expire all connections.
This command does not disable packet inspection.
.It Ic show
Show the current state and configuration.
Syntax of printed configuration is for the user and may not match the
.Xr npf.conf 5
syntax.
.It Ic validate Op Ar path
Validate the configuration file and the processed form.
The configuration file at
.Pa /etc/npf.conf
will be used unless a file is specified by
.Ar path .
The
.Ar path
may also be set to "-" for reading from
.Em stdin .
.\" ---
.It Ic rule Ar name Ic add Aq rule-syntax
Add a rule to a dynamic ruleset specified by
.Ar name .
On success, returns a unique identifier which can be used to remove
the rule with
.Ic rem-id
command.
The identifier is alphanumeric string.
.It Ic rule Ar name Ic rem Aq rule-syntax
Remove a rule from a dynamic ruleset specified by
.Ar name .
This method uses SHA1 hash computed on a rule to identify it.
Although very unlikely, it is subject to hash collisions.
For a fully reliable and more efficient method, it is recommended to use
.Ic rem-id
command.
.It Ic rule Ar name Ic rem-id Aq id
Remove a rule specified by unique
.Ar id
from a dynamic ruleset specified by
.Ar name .
.It Ic rule Ar name Ic list
List all rules in the dynamic ruleset specified by
.Ar name .
.It Ic rule Ar name Ic flush
Remove all rules from the dynamic ruleset specified by
.Ar name .
.\" ---
.It Ic table Ar name Ic add Aq Ar addr/mask
In table
.Ar name ,
add the IP address and optionally netmask, specified by
.Aq Ar addr/mask .
Only the tables of type "lpm" support masks.
.It Ic table Ar name Ic rem Aq Ar addr/mask
In table
.Ar name ,
remove the IP address and optionally netmask, specified by
.Aq Ar addr/mask .
Only the tables of type "lpm" support masks.
.It Ic table Ar name Ic test Aq Ar addr
Query the table
.Ar name
for a specific IP address, specified by
.Ar addr .
If no mask is specified, a single host is assumed.
.It Ic table Ar name Ic list
List all entries in the currently loaded table specified by
.Ar name .
This operation is expensive and should be used with caution.
.It Ic table Ar name Ic replace Oo Fl n Ar newname Oc Oo Fl t Ar type Oc Aq Ar path
Replace the existing table specified by
.Ar name
with a new table built from the file specified by
.Ar path .
Optionally, the new table will:
.Bl -tag -width xxxxxxxxxx -compact -offset 3n
.It Fl n Ar newname
be named
.Ar newname ,
effectively renaming the table.
If not specified, the name of the table being replaced will be used.
.It Fl t Ar type
be of type
.Ar type ;
currently supported types are
.Cm ipset ,
.Cm lpm ,
or
.Cm const .
If not specified, the type of the table being replaced will be used.
.El
.\" ---
.It Ic save Op Ar path
Save the active configuration with a snapshot of the current connections.
The data will be stored in the
.Pa /var/db/npf.db
file unless a file is specified by
.Ar path .
Administrator may want to stop the packet inspection before saving.
.It Ic load
Load the saved configuration file and the connections from the file.
Note that any existing connections will be destroyed.
Administrator may want to start packet inspection after the load.
.It Ic stats
Print various statistics.
.It Ic debug ( Fl a | Fl b Ar binary-config | Fl c Ar config ) \
Oo Fl o Ar outfile Oc
Process the active configuration (if
.Fl a
is set), the given binary configuration (if
.Fl b
is set) or the given the plain configuration (if
.Fl c
is set).
Print the byte-code of each rule and the encoded configuration data.
Also, if
.Fl o
is set, write the binary configuration data into the given file.
.Pp
This is primarily for developer use.
.It Ic list Oo Fl 46hNnW Oc Op Fl i Ar ifname
Display a list of tracked connections:
.Bl -tag -width xxxxxxxxx -compact -offset 3n
.It Fl 4
Display only IPv4 connections.
.It Fl 6
Display only IPv6 connections.
.It Fl h
Don't display a header.
.It Fl N
Try to resolve addresses.
.It Fl n
Only show NAT connections.
.It Fl W
Restrict the display width.
.It Fl i Ar ifname
Display only connections through the named interface.
.El
.El
.Sh PERFORMANCE
Reloading the configuration is a relatively expensive operation.
Therefore, frequent reloads should be avoided.
Use of tables should be considered as an alternative design.
See
.Xr npf.conf 5
for details.
.\" -----
.Sh FILES
.Bl -tag -width Pa -compact
.It Pa /dev/npf
control device
.It Pa /etc/npf.conf
default configuration file
.El
.\" -----
.Sh EXAMPLES
Starting the NPF packet filter:
.Bd -literal -offset indent
# npfctl reload
# npfctl start
# npfctl show
.Ed
.Pp
Addition and removal of entries in the table whose ID is "vip":
.Bd -literal -offset indent
# npfctl table "vip" add 10.0.0.1
# npfctl table "vip" rem 182.168.0.0/24
.Ed
.Pp
Replacing the existing table which has ID "svr"
with a new const table populated from file "/tmp/npf_vps_new",
and renamed to "vps":
.Bd -literal -offset indent
# npfctl table "svr" replace -n "vps" -t const "/tmp/npf_vps_new"
.Ed
.\" -----
.Sh SEE ALSO
.Xr bpf 4 ,
.Xr npf.conf 5 ,
.Xr npf 7 ,
.Xr npfd 8
.Sh HISTORY
NPF first appeared in
.Nx 6.0 .
.Sh AUTHORS
NPF was designed and implemented by
.An Mindaugas Rasiukevicius .