diff options
Diffstat (limited to 'usr/src/man/man8/svc.ipfd.8')
| -rw-r--r-- | usr/src/man/man8/svc.ipfd.8 | 626 |
1 files changed, 626 insertions, 0 deletions
diff --git a/usr/src/man/man8/svc.ipfd.8 b/usr/src/man/man8/svc.ipfd.8 new file mode 100644 index 0000000000..eb1c6876fb --- /dev/null +++ b/usr/src/man/man8/svc.ipfd.8 @@ -0,0 +1,626 @@ +'\" 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 +.\" Copyright 2016 Hans Rosenfeld <rosenfeld@grumpf.hope-2000.org> +.TH SVC.IPFD 8 "Dec 30, 2015" +.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 +.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" +.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(5). +.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" +.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(7)), 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\fBblock-policy\fR\fR +.ad +.sp .6 +.RS 4n +The \fBblock-policy\fR property defines the handling of packets that +are blocked by the filter. It has the following modes: +.sp +.ne 2 +.na +\fB\fBnone\fR block-policy mode\fR +.ad +.sp .6 +.RS 4n +Block by dropping packets. +.RE + +.sp +.ne 2 +.na +\fB\fBreturn\fR block-policy mode\fR +.ad +.sp .6 +.RS 4n +Block by returning RST (for TCP) or ICMP messages (for other +protocols) to the sender of the blocked packets. +.RE + +.RE + +.sp +.ne 2 +.na +\fB\fBapply_to\fR\fR +.ad +.sp .6 +.RS 4n +A multi-value property listing IPv4 network source entities to enforce the +chosen policy mode. Packets coming from the 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\fBapply_to_6\fR\fR +.ad +.sp .6 +.RS 4n +A multi-value property listing IPv6 network source entities to enforce the +chosen policy mode. Packets coming from the entities listed in \fBapply_to_6\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:2001:DB8::12ff:fe34:5678" +subnet: network:\fIIP/netmask\fR "network:2001:DB8::/32" +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 IPv4 network source 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 +.ne 2 +.na +\fB\fBexceptions_6\fR\fR +.ad +.sp .6 +.RS 4n +A multi-value property listing IPv6 network source entities to be excluded from +the \fBapply_to_6\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_6\fR property. This property has the same value syntax as +\fBapply_to_6\fR property. +.RE + +.sp +.ne 2 +.na +\fB\fBtarget\fR\fR +.ad +.sp .6 +.RS 4n +A multi-value property listing IPv4 network destination entities to enforce the +chosen policy mode. Packets directed to the destination entities listed in +\fBtarget\fR property will be denied if policy is \fBdeny\fR and allowed if +policy is \fBallow\fR. This property has the same value syntax as \fBapply_to\fR +property, with the notable exception that specifying network interfaces is not +supported. +.RE + +.sp +.ne 2 +.na +\fB\fBtarget_6\fR\fR +.ad +.sp .6 +.RS 4n +A multi-value property listing IPv6 network destination entities to enforce the +chosen policy mode. Packets directed to the destination entities listed in +\fBtarget_6\fR property will be denied if policy is \fBdeny\fR and allowed if +policy is \fBallow\fR. This property has the same value syntax as +\fBapply_to_6\fR property, with the notable exception that specifying network +interfaces is not supported. +.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 inherit the Global Default firewall policy. +.RE + +.sp +.ne 2 +.na +\fB\fBfirewall_config/block_policy\fR\fR +.ad +.sp .6 +.RS 4n +A service's block policy can also be set to \fBuse_global\fR. Services with +\fBuse_global\fR block policy mode inherit the Global Default firewall block +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(8) 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" +.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" +.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 +.LP +See \fBattributes\fR(7) 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 +.LP +.BR svcprop (1), +.BR svcs (1), +.BR getservbyname (3SOCKET), +.BR rpc (5), +.BR attributes (7), +.BR ipfilter (7), +.BR smf (7), +.BR ipf (8), +.BR svcadm (8), +.BR svccfg (8) |