netconfig.8

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.TH NETCONFIG 8 "October 2008" "sysconfig" "Network configuration"
.SH NAME
netconfig \- modular tool to modify network configuration
.SH SYNOPSIS

.B netconfig modify
.RS
.PD 0
.P
.RB " < " \-s " | " \-\-service " <service name> > "
.P
.RB " [ " \-i " | " \-\-interface " <interface name> ] "
.P
.RB " [ " \-F " | " \-\-input\-format " <input/lease file format> ] "
.P
.RB " [ " \-I " | " \-\-input\-file " <input/lease file name> ] "
.P
.RB " [ " \-l " | " \-\-lease\-file " <input/lease file name> ] "
.P
.RB " [ " \-m " | " \-\-module\-only " < name | prefix > ] "
.P
.RB " [ " \-f " | " \-\-force\-replace " ] "
.P
.RB " [ " \-v " | " \-\-verbose " ] "
.PD
.RE

.B netconfig remove
.RS
.PD 0
.P
.RB " < " \-s " | " \-\-service " <service name> > "
.P
.RB " [ " \-i " | " \-\-interface " <interface name> ] "
.P
.RB " [ " \-m " | " \-\-module\-only " < name | prefix > ] "
.P
.RB " [ " \-f " | " \-\-force\-replace " ] "
.P
.RB " [ " \-v " | " \-\-verbose " ] "
.PD
.RE

.B netconfig update
.RS
.PD 0
.P
.RB " [ " \-m " | " \-\-module\-only " < name | prefix > ] "
.P
.RB " [ " \-f " | " \-\-force\-replace " ] "
.P
.RB " [ " \-v " | " \-\-verbose " ] "
.PD
.RE

.B netconfig
.RB "< " \-h " | " \-\-help " > "

.SH DESCRIPTION
Netconfig is a modular tool to manage additional network configuration settings.
It merges statically defined settings with settings provided by autoconfiguration
mechanisms as dhcp or ppp according to a predefined policy and applies the
required changes to the system by calling netconfig modules.

Each netconfig module is responsible to apply a set of changes for instance by
writing of a configuration file and restarting a service or similar.

The netconfig tool knows three main actions:
.TP
.B modify
Modify the current \fIinterface\fR and \fIservice\fR specific dynamic settings
and update the network configuration.

Netconfig reads these settings on its standard input or from the file specified
by the \fI\-\-input\-file\fR option and stores them internally until a system
reboot or the next modify or remove action. Already existing settings for the
same interface and service combination will be overwritten.
See the \fIMODIFY INPUT FORMAT\fR section for input format description.

.TP
.B remove
Removes the dynamic settings provided by a
.B modify
action for the specified
.I interface
and
.I service
combination and update the network configuration.

.TP
.B update
Update the network configuration using current settings. This also required when
the policy or the static configuration in sysconfig/network/config changed.

The update can be limited to a group of modules with a common prefix or to a
single module name using the \fI-m name-or-prefix\fR option, for example use
\fI-m dns\fR to apply all dns settings or \fI-m dns-resolver\fR to apply only
settings handled in the dns-resolver module.
Note: Especially the second call may cause inconsistent system configuration!
.PP
The netconfig policy and the static configuration settings are defined in
.I /etc/sysconfig/network/config
variables by the administrator using YaST2, NetworkManager or manually as
defined in
.I NETCONFIG VARIABLES section.

The dynamic configuration settings provided by autoconfiguration tools as dhcp
or ppp are delivered to netconfig directly by these tools with the
.B modify
and
.B remove
netconfig actions.

.SH NETCONFIG VARIABLES
.TP
.B NETCONFIG_MODULES_ORDER
This variable defines the start order of netconfig modules installed
in the \fB/etc/netconfig.d/\fR directory.

To disable the execution of a module, don't remove it from the list
but prepend it with a minus sign, \fI-ntp-runtime\fR.
.TP
.B NETCONFIG_\fI<set>\fB_POLICY
Netconfig defines a merge policy variable for each set of network settings.
An empty policy variable disables any modifications in netconfig.

This variable lists the network interfaces, that netconfig has to consider
as a valid source for this set of settings and in which order.

Except of complete interface names, also basic wildcards to match multiple
interfaces are allowed. For example, \fI"eth* ppp?"\fR will target first
all \fIeth\fR and then all \fIppp0\fR-\FIppp9\fR interfaces.

There are two special predefined policy values which indicate how to apply
the static settings defined in the corresponding
\fBNETCONFIG_\fI<set>\fB_STATIC_*\fR variables:

.RS
.PD 0
.TP
.BR STATIC
the static settings have to be merged together with the dynamic settings.

.TP
.BR STATIC_FALLBACK
the static settings have to be used only, when no dynamic are avaliable.
.PD
.RE
.RS

By default, the policy is set to the special value \fBauto\fR. This special
policy value is resolved differently by netconfig when the NetworkManager
is enabled or disabled:
.RS
.PD 0

.TP
.IR NetworkManager \ is \ disabled
The \fBauto\fR policy value is resolved to a policy "\fBSTATIC *\fR".

.TP
.IR NetworkManager \ is \ enabled
The \fBauto\fR policy value is resolved to "\fBSTATIC_FALLBACK * NetworkManager\fR"
causing to use the NetworkManager build-in merge policy with a fallback to
the static settings defined in netconfig variables when the NetworkManager
does not provide any. Since version 0.84.3, the policy permits also other
non-NetworkManager per interface settings provided by other services.

Note:
NetworkManager is not using any of the statically defined netconfig settings.
.br
Please use the (k)nm connection editor to define yout network settings for
the NetworkManager!
.PD
.RE
.RS

.RE

.SS DNS
.TP
.B NETCONFIG_DNS_POLICY
Defines the DNS merge policy.
See also the \fBNETCONFIG_\fI<set>\fB_POLICY\fR section.
.TP
.B NETCONFIG_DNS_FORWARDER
The name of the DNS forwarder that has to be configured. Currently
implemented are "bind" (dns-bind module), "dnsmasq" (dns-dnsmasq)
and "resolver" (dns-resolver module), that causes to write the name
server IP addresses directly to /etc/resolv.conf only (no forwarder).
Empty string defaults to "resolver", that is also the default setting.

See also \fBNETCONFIG MODULES\fR section for more informations.
.TP
.B NETCONFIG_DNS_FORWARDER_FALLBACK
When enabled (default) in forwarder mode ("bind", "dnsmasq"), netconfig
writes an explicit localhost nameserver address to the /etc/resolv.conf,
followed by the policy resolved name server list as fallback for the
moments, when the local forwarder is stopped. Otherwise, the fallback is
written only, when the NETCONFIG_DNS_STATIC_SERVERS variable contains an
localhost address.
.TP
.B NETCONFIG_DNS_STATIC_SEARCHLIST
List of DNS domain names used for host-name lookup.

It is written as search list into the /etc/resolv.conf file.
.TP
.B NETCONFIG_DNS_STATIC_SERVERS
List of namserver IP addresses used for host-name lookup.

When the NETCONFIG_DNS_FORWARDER variable is set to "resolver", the name
servers are written directly to /etc/resolv.conf.

Otherwise, the nameserver are written into a forwarder specific configuration
file. Whether the nameservers are written as fallback to the /etc/resolv.conf,
depends on the NETCONFIG_DNS_FORWARDER_FALLBACK variable.
When the /etc/resolv.conf does not contain any nameservers, the glibc makes
use of the name server running on the local machine (the forwarder). See also
\fBNETCONFIG MODULES\fR section
for more informations.
.TP
.B NETCONFIG_DNS_RANKING
Allows to specify a custom DNS service ranking list, that is which services
provide preferred (e.g. vpn services), and which services fallback settings
(e.g. avahi). It causes a per service sorting of the nameservers and search
list settings.
Preferred service names have to be prepended with a \fB"+"\fR, fallback
service names can be marked with a \fB"\-"\fR character. Instead of the
service name also a regex is supported using +/pattern/ and -/pattern/.
The special default value \fI"auto"\fR enables the build-in service ranking
list, currently:
.nf
    "+/vpn/ -/auto/ +strongswan +openswan +racoon -avahi"
.fi
the value \fI"none"\fR or \fI""\fR allows to disable the ranking / sorting.
.TP
.B NETCONFIG_DNS_RESOLVER_OPTIONS
Allows to specify options to use when writting the /etc/resolv.conf,
for example:
.nf
     "debug attempts:1 timeout:10"
.fi
See resolv.conf(5) manual page for details.
.TP
.B NETCONFIG_DNS_RESOLVER_SORTLIST
Allows to specify a sortlist to use when writting the /etc/resolv.conf,
for example:
.nf
	"130.155.160.0/255.255.240.0 130.155.0.0"
.fi
See resolv.conf(5) manual page for details.

.SS NTP
.TP
.B NETCONFIG_NTP_POLICY
Defines the NTP merge policy.
See also the \fBNETCONFIG_\fI<set>\fB_POLICY\fR section.
.TP
.B NETCONFIG_NTP_STATIC_SERVERS
List of NTP server IP addresses.

.SS NIS
.B NETCONFIG_NIS_POLICY
Defines the NIS / YP merge policy.
See also the \fBNETCONFIG_\fI<set>\fB_POLICY\fR section.
.TP
.BR NETCONFIG_NIS_STATIC_DOMAIN " [ " _ "<number> ]"
A NIS domain name.
.TP
.BR NETCONFIG_NIS_STATIC_SERVERS " [ " _ "<number> ]"
A list of NIS servers for the domain with same suffix number.
.TP
.BR NETCONFIG_NIS_SETDOMAINNAME
Defines whether to set the NIS domain using a setdomainname(2) call.
When enabled and the NIS domain is not provided dynamically or defined
in the static netconfig variables, the domain from /etc/defaultdomain
is used as fallback. Valid values are:
.RS
.PD 0
.TP
.IR no
netconfig does not set the domainname at all
.TP
.IR yes
netconfig sets the domainname according to the NIS policy using the
settings of the first interface and service which provided the NIS
domainname.
.TP
.RI "<" interface ">"
netconfig sets the domainname according to the NIS policy using the
settings of the first service which provided the NIS domainname on
the specified interface.
.PD
.RE

.SH NETCONFIG MODULES
.TP
.B dns-resolver
This module writes the DNS settings into the \fI/etc/resolv.conf\fR file.

When the \fBNETCONFIG_DNS_FORWARDER\fR variable is empty or set to "resolver",
both, the domain search list and the nameserver list is written.

Otherwise, only the domain search list is written. Whether the nameservers are
written to the /etc/resolv.conf or handled by the forwarder specific module
(e.g. bind) only, depends on the NETCONFIG_DNS_FORWARDER_FALLBACK variable.
.TP
.B dns-bind
This module writes the DNS nameservers as forwarders for the bind nameserver
into the \fI/etc/named.d/forwarders.conf\fR file. Please verify that this
file is included in the \fIoptions section\fR of \fI/etc/named.conf\fR, like:
.nf
options {
	#forward                first;
	include                 "/etc/named.d/forwarders.conf";
# [...]
.fi
You can use the yast2 dns-server module to configure bind as forwarder.
.TP
.B dns-dnsmasq
This module writes the DNS nameservers as forwarders for the dnsmasq nameserver
into the \fI/var/run/dnsmasq-forwarders.conf\fR file. Please verify, that this
file is set in the \fBresolv-file\fR keyword in the \fI/etc/dnsmasq.conf\fR.
.TP
.B ntp-runtime
The netconfig ntp-runtime module does not alter the \fI/etc/ntp.conf\fR file,
but makes use of NTP "runtime configuration".

The list of the NTP servers is written to the \fI/var/run/ntp/servers-netconfig\fR
file and if the configuration changed meanwhile, the ntp service will be restarted
using "rcntp try-restart". The ntp init script provides the functionality to apply
the server list at runtime to the \fBntpd\fR(1) daemon.
.TP
.B nis
This module writes the NIS configuration into the \fI/etc/ypconf\fR file and
reloads the "ypbind" service when the configuration changed.

.SH MODIFY INPUT FORMAT
The \fBnetconfig modify\fR command expects a simple, single quoted, key-value
parameter list in a dhcpcd info file compatible format. The keywords have to
be usable as variable name in a shell (identifier).
The keyword \fBINTERFACE\fR is mandatory. The currently considered key-value
pairs are:
.RS
.PD 0
.P
.BR INTERFACE "='<interface name>'"
.P
.BR IPADDR "='<IP address> [/<prefix length>]'"
.P
.BR NETMASK "='<network mask>'"
.P
.BR NETWORK "='<network address>'"
.P
.BR BROADCAST "='<broadcast address>'"
.P
.BR ROUTES "='<space separated list of classless route entries>'
.br
Each route entry consists of "network,netmask,router" addresses.
.P
.BR GATEWAYS "='<space separated list of gateway IP addresses>'"
.P
.BR DNSSEARCH "='<space separated list of DNS domain names>'"
.P
.BR DNSDOMAIN "='<DNS domain name>'"
.P
.BR DNSSERVERS "='<space separated list of DNS nameserver addresses>'"
.P
.BR NTPSERVERS "='<space separated list of ntp server addresses>'"
.P
.BR NISDOMAIN "='<NIS domain name>'"
.P
.BR NISSERVERS "='<list of server addresses for the NIS domain>'"
.P
.BR NETBIOSNAMESERVER "='<list of netbios nameserver addresses>'"
.PD
.RE

.SH MODIFY VARIABLE EXAMPLES
See also the output of the \fIdhcpcd-test <interface name>\fR command.
.br
Following variables are used by the current netconfig modules:
.SS DNS
.nf
DNSSEARCH='example.net example.com'
DNSDOMAIN='example.com'
DNSSERVERS='192.168.0.10 192.168.0.20'
.fi
.SS NTP
.nf
NTPSERVERS='192.168.0.10 192.168.0.20'
.fi
.SS NIS
.nf
NISDOMAIN='example.com'
NISSERVERS='192.168.0.20 192.168.0.10'
.fi

.SH BUGS
Please report bugs at <http://www.suse.de/feedback>

.SH AUTHORS
.nf
Michael Calmer <mc@suse.de>
Marius Tomaschewski <mt@suse.de>
Milisav Radmanic <radmanic@suse.de>
.fi

.SH "SEE ALSO"
.BR ifcfg (5),
.br
.BR /etc/sysconfig/network/config .