path: root/usr/src/man/man1m/svc.ipfd.1m

'\" te
.\" To view license terms, attribution, and copyright for IP Filter, the default path is /usr/lib/ipf/IPFILTER.LICENCE. If the Solaris operating environment has been installed anywhere other than the default, modify the given path to access the file at the installed
.\" location.
.\" Copyright (c) 2009, Sun Microsystems, Inc. All Rights Reserved
.TH SVC.IPFD 1M "Jan 13, 2009"
.SH NAME
svc.ipfd \- IP Filter firewall monitoring daemon
.SH SYNOPSIS
.LP
.nf
\fB/lib/svc/bin/svc.ipfd\fR
.fi

.LP
.nf
\fBsvc:/network/ipfilter:default\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBsvc.ipfd\fR daemon monitors actions on services that use firewall
configuration and initiates update services' IP Filter configuration. The
daemon allows the system to react to changes in system's firewall configuration
in an incremental fashion, at a per-service level.
.sp
.LP
A service's firewall policy is activated when it is enabled, deactivated when
it is disabled, and updated when its configuration property group is modified.
\fBsvc.ipfd\fR monitors the services management facility (SMF) repository for
these actions and invokes the IP Filter rule-generation process to carry out
the service's firewall policy.
.sp
.LP
This daemon is started by the \fBnetwork/ipfilter\fR service either through the
\fBstart\fR or \fBrefresh\fR method. Thus, the daemon inherits the environment
variables and credentials from the method and runs as root with all zone
privileges.
.SS "Firewall Static Configuration"
.sp
.LP
A static definition describes a service's network resource configuration that
is used to generate service-specific IPF rules. The per-service
\fBfirewall_context\fR property group contains a service's static definition,
similar to the \fBinetd\fR property group in \fBinetd\fR managed services. This
property group supports:
.sp
.ne 2
.na
\fB\fBfirewall_context/name\fR\fR
.ad
.sp .6
.RS 4n
For non-\fBinetd\fR services. The IANA name or RPC name, equivalent to the
\fBinetd/name\fR property.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_context/isrpc\fR\fR
.ad
.sp .6
.RS 4n
For non-\fBinetd\fR services. A boolean property where a \fBtrue\fR value
indicates an RPC service, equivalent to the \fBinetd/isrpc\fR property. For RPC
services, the value of \fBfirewall_context/name\fR is not an IANA name but is
either an RPC program number or name. See \fBrpc\fR(4).
.RE

.sp
.LP
Additionally, some services may require a mechanism to generate and supply
their own IPF rules. An optional property \fBipf_method\fR, provides a
mechanism to allow such custom rule generation:
.sp
.ne 2
.na
\fB\fBfirewall_context/ipf_method\fR\fR
.ad
.sp .6
.RS 4n
A command. Normally a script that generates IPF rules for a service. The
framework does not generate rules for services with this property definition.
Rather, the framework expects these services to provide their own rules.
.RE

.sp
.LP
A service's \fBipf_method\fR specifies a command that takes an additional
argument, its own fault management resource identifier (FMRI), and generates
the service's firewall rules and outputs those rules to stdout. To generate
rules for a service with the \fBipf_method\fR property, the framework execs the
command specified in \fBipf_method\fR, passing the service FMRI as the
additional argument, and stores the rules for that service by redirecting the
command output, the rules, to the service's rule file. Because an
\fBipf_method\fR is \fBexec\fR'ed from the context of either the
\fBnetwork/ipfilter\fR \fBstart\fR or \fBrefresh\fR method process, it inherits
the execution context and runs as root.
.sp
.LP
The service static configuration is delivered by the service developer and not
intended to be modified by users. These properties are only modified upon
installation of an updated service definition.
.SS "Firewall Policy Configuration"
.sp
.LP
A per-service property group, \fBfirewall_config\fR, stores the services'
firewall policy configuration. Because \fBnetwork/ipfilter:default\fR is
responsible for two firewall policies, the Global Default and Global Override
system-wide policies (as explained in \fBipfilter\fR(5)), it has two property
groups, \fBfirewall_config_default\fR and \fBfirewall_config_override\fR, to
store the respective system-wide policies.
.sp
.LP
Below are the properties, their possible values, and corresponding semantics:
.sp
.ne 2
.na
\fB\fBpolicy\fR\fR
.ad
.sp .6
.RS 4n
The \fBpolicy\fR has the following modes:
.sp
.ne 2
.na
\fB\fBnone\fR policy mode\fR
.ad
.sp .6
.RS 4n
No access restriction. For a global policy, this mode allows all incoming
traffic. For a service policy, this mode allows all incoming traffic to its
service.
.RE

.sp
.ne 2
.na
\fB\fBdeny\fR policy mode\fR
.ad
.sp .6
.RS 4n
More restrictive than \fBnone\fR. This mode allows incoming traffic from all
sources except those specified in the \fBapply_to\fR property.
.RE

.sp
.ne 2
.na
\fB\fBallow\fR policy mode\fR
.ad
.sp .6
.RS 4n
Most restrictive mode. This mode blocks incoming traffic from all sources
except those specified in the \fBapply_to\fR property.
.RE

.RE

.sp
.ne 2
.na
\fB\fBapply_to\fR\fR
.ad
.sp .6
.RS 4n
A multi-value property listing network entities to enforce the chosen policy
mode. Entities listed in \fBapply_to\fR property will be denied if policy is
\fBdeny\fR and allowed if policy is \fBallow\fR. The syntax for possible values
are:
.sp
.in +2
.nf
host:           host:\fIIP\fR                 "host:192.168.84.14"
subnet:         network:\fIIP/netmask\fR      "network:129.168.1.5/24"
ippool:         pool:\fIpool number\fR        "pool:77"
interface:      if:\fIinterface_name\fR       "if:e1000g0"
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fBexceptions\fR\fR
.ad
.sp .6
.RS 4n
A multi-value property listing network entities to be excluded from the
\fBapply_to\fR list. For example, when \fBdeny\fR policy is applied to a
subnet, exceptions can be made to some hosts in that subnet by specifying them
in the \fBexceptions\fR property. This property has the same value syntax as
\fBapply_to\fR property.
.RE

.sp
.LP
For individual network services only:
.sp
.ne 2
.na
\fB\fBfirewall_config/policy\fR\fR
.ad
.sp .6
.RS 4n
A service's policy can also be set to \fBuse_global\fR. Services with
\fBuse_global\fR policy mode inherits the Global Default firewall policy.
.RE

.sp
.LP
For the Global Default only:
.sp
.ne 2
.na
\fB\fBfirewall_config_default/policy\fR\fR
.ad
.sp .6
.RS 4n
Global Default policy, \fBfirewall_config\fR property group in
\fBsvc:/network/ipfilter:default\fR, can also be set to \fBcustom\fR. Users can
set \fBpolicy\fR to \fBcustom\fR to use prepopulated IP Filter configuration,
for example, an existing IP Filter configuration or custom configurations that
cannot be provided by the framework. This Global Default-only policy mode
allows users to supply a text file containing the complete set of IPF rules.
When \fBcustom\fR mode is selected, the specified set of IPF rules is
\fBcomplete\fR and the framework will not generate IPF rules from configured
firewall policies.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_config_default/custom_policy_file\fR\fR
.ad
.sp .6
.RS 4n
A file path to be used when Global Default policy is set to \fBcustom\fR. The
file contains a set of IPF rules that provide the desired IP Filter
configuration. For example, users with existing IPF rules in
\fB/etc/ipf/ipf.conf\fR can execute the following commands to use the existing
rules:
.RS +4
.TP
1.
Set custom policy:
.sp
.in +2
.nf
# \fBsvccfg -s ipfilter:default setprop \e
firewall_config_default/policy = astring: "custom"\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
2.
Specify custom file:
.sp
.in +2
.nf
# \fBsvccfg -s ipfilter:default setprop \e
firewall_config_default/custom_policy_file = astring: \e\fR
\fB"/etc/ipf/ipf.conf"\fR
.fi
.in -2
.sp

.RE
.RS +4
.TP
3.
Refresh configuration:
.sp
.in +2
.nf
# \fBsvcadm refresh ipfilter:default\fR
.fi
.in -2
.sp

.RE
.RE

.sp
.ne 2
.na
\fB\fBfirewall_config_default/open_ports\fR\fR
.ad
.sp .6
.RS 4n
Non-service program requiring allowance of its incoming traffic can request
that the firewall allow traffic to its communication ports. This multi-value
property contains protocol and port(s) tuple in the form:
.sp
.in +2
.nf
"{tcp | udp}:{\fIPORT\fR | \fIPORT\fR-\fIPORT\fR}"
.fi
.in -2
.sp

.RE

.sp
.LP
Initially, the system-wide policies are set to \fBnone\fR and network services'
policies are set to \fBuse_global\fR. Enabling \fBnetwork/ipfilter\fR activates
the firewall with an empty set of IP Filter rules, since system-wide policy is
\fBnone\fR and all services inherit that policy. To configure a more
restrictive policy, use \fBsvccfg\fR(1M) to modify network services and
system-wide policies.
.sp
.LP
A user configures firewall policy by modifying the service's
\fBfirewall_config\fR property group. A new authorization,
\fBsolaris.smf.value.firewall.config\fR, is created to allow delegation of the
firewall administration privilege to users. Users with Service Operator
privileges will need this new authorization to be able to configure firewall
policy.
.SS "Firewall Availability"
.sp
.LP
During boot, a firewall is configured for enabled services prior to the
starting of those services. Thus, services are protected on boot. While the
system is running, administrative actions such as service restarting, enabling,
and refreshing may cause a brief service vulnerability during which the service
runs while its firewall is being configured.
.sp
.LP
\fBsvc.ipfd\fR monitors a service's start and stop events and configures or
unconfigures a service's firewall at the same time that SMF is starting or
stopping the service. Because the two operations are simultaneous, there is a
possible window of exposure (less than a second) if the service is started
before its firewall configuration completed. RPC services typically listen on
ephemeral addresses, which are not known until the services are actually
running. Thus RPC services are subjected to similar exposure since their
firewalls are not configured until the services are running.
.SS "Developer Documentation"
.sp
.LP
Services providing remote capabilities are encouraged to participate in the
firewall framework to control network access to the service. While framework
integration is not mandatory, remote access to services that are not integrated
in the framework may not function correctly when a system-wide policy is
configured.
.sp
.LP
Integrating a service into the framework is as straightforward as defining two
additional property groups and their corresponding properties in the service
manifest. IP Filter rules are generated when a user enables the service. In the
non-trivial case of custom rule generation, where a shell script is required,
there are existing scripts that can be used as examples.
.sp
.LP
The additional property groups, \fBfirewall_config\fR and
\fBfirewall_context\fR, stores firewall policy configuration and provides
static firewall definition, respectively. Below is a summary of new property
groups and properties and their appropriate default values.
.sp
.LP
Firewall policy configuration:
.sp
.ne 2
.na
\fB\fBfirewall_config\fR\fR
.ad
.sp .6
.RS 4n
Access to the system is protected by a new authorization definition and a
user-defined property type. The new authorization should be assigned to the
property group \fBvalue_authorization\fR property in a way such as:
.sp
.in +2
.nf
<propval name='value_authorization' type='astring'
value='solaris.smf.value.firewall.config' />
.fi
.in -2
.sp

A third party should follow the service symbol namespace convention to generate
a user-defined type. Sun-delivered services can use
\fBcom.sun,fw_configuration\fR as the property type.
.sp
See "Firewall Policy Configuration," above, for more information.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_config/policy\fR\fR
.ad
.sp .6
.RS 4n
This property's initial value should be \fBuse_global\fR since services, by
default, inherit the Global Default firewall policy.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_config/apply_to\fR\fR
.ad
.sp .6
.RS 4n
An empty property, this property has no initial value.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_config/exceptions\fR\fR
.ad
.sp .6
.RS 4n
An empty property, this property has no initial value.
.RE

.sp
.LP
Firewall static definition:
.sp
.ne 2
.na
\fB\fBfirewall_context\fR\fR
.ad
.sp .6
.RS 4n
A third party should follow service symbol namespace convention to generate a
user-defined type, Sun delivered services can use \fBcom.sun,fw_definition\fR
as the property type.
.sp
See "Firewall Static Configuration," above, for more information.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_context/name\fR\fR
.ad
.sp .6
.RS 4n
Service with well-known, IANA defined port, which can be obtained by
\fBgetservbyname\fR(3SOCKET). The service's IANA name is stored in this
property. For RPC services, the RPC program number is stored in this property.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_context/isrpc\fR\fR
.ad
.sp .6
.RS 4n
For RPC services, this property should be created with its value set to
\fBtrue\fR.
.RE

.sp
.ne 2
.na
\fB\fBfirewall_context/ipf_method\fR\fR
.ad
.sp .6
.RS 4n
In general, the specified firewall policy is used to generate IP Filter rules
to the service's communication port, derived from the
\fBfirewall_context/name\fR property. Services that do not have IANA-defined
ports and are not RPC services will need to generate their own IP Filter rules.
Services that generate their own rules may choose not to have
\fBfirewall_context/name\fR and \fBfirewall_context/isrpc\fR properties. See
the following services:
.sp
.in +2
.nf
svc:/network/ftp:default
svc:/network/nfs/server:default
svc:/network/ntp:default
.fi
.in -2
.sp

\&...and others with the \fBipf_method\fR for guidance.
.RE

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Committed
.TE

.SH SEE ALSO
.sp
.LP
\fBsvcprop\fR(1), \fBsvcs\fR(1), \fBipf\fR(1M), \fBsvcadm\fR(1M),
\fBsvccfg\fR(1M), \fBgetservbyname\fR(3SOCKET), \fBrpc\fR(4),
\fBattributes\fR(5), \fBipfilter\fR(5), \fBsmf\fR(5)