modify_resolvconf(8)

NAME
modify_resolvconf - modify /etc/resolv.conf

SYNOPSIS

modify_resolvconf modify -s <service> -t <text>|- -p <process> [ -i <pid> ] -f <filename of script> [ -e <extension> ] [ -l <list of search domains> | -d <domainname> ] [ -n <list of nameservers> ] [ -a <filename> ] [ -o <filename> ] [ --resolv ] [ --named ] [ --no_restart ] [ -v ] [ -q ]

modify_resolvconf restore -s <service> [ -e <extension> ] [ -n show ] [ -o <filename> ] [ -k ] [ --resolv ] [ --named ] [ --no_restart ] [ -v ] [ -q ]

modify_resolvconf cleanup [ -n show P ] [ -o <filename> ] [ -k ] [ --resolv ] [ --named ] [ --no_restart ] [ -v ] [ -q ]

modify_resolvconf check [ --resolv ] [ --named ] [ -v ] [ -q ]

modify_resolvconf -h, --help

DESCRIPTION
modify_resolvconf can be used by programs that have to change /etc/resolv.conf or /etc/named.conf dynamically (temporarily). It provides a means to do that in a consistent way accross the system. The idea is to

- make a backup
    that can be restored later. Therefore, a fixed naming scheme is used (see below). Every modification creates a new backup. These will be restored correctly even if it happens in another sequence. If a service crashes, there is a way to clean up stale modification and to restore the original configuration.

- add an informational header
    to the new configuration file that informs the user (or other programs) that is was changed temporarily, who changed the file, why it was done and how to avoid it in the future. This header is automatically created by modify_resolvconf and is therefore standardized. It is just the presence of this header what marks it as temporarily modified.

- trigger needed actions
    like restarting named if /etc/named.conf was changed or copy a modified /etc/resolv.conf to postfix's chroot environment.

It is recommended to make use of modify_resolvconf in every script that modifies /etc/resolv.conf or /etc/named.conf temporarily. It should not be used to write a definitive version of these files (e.g. by YaST or some installation tool). The naming scheme used for backup copies is: /etc/resolv.conf.saved.by.<service name>.<extension> where service name is one of e.g. dhclient, dhcpcd, pppd, ipppd, pcmcia, hotplug (these are the major candidates) and private extension might optionally be used by the service itself if it modifies twice, e.g. for different interfaces. This naming scheme allows restoring /etc/resolv.conf at boottime after a crash of the system or at starttime of the service (after a crash of the service). modify_resolvconf can be controlled with two variables in SuSE's /etc/sysconfig/network/config. With MODIFY_RESOLV_CONF_DYNAMICALLY you can allow/disallow dynamic changes to /etc/resolv.conf. If you like /etc/named.conf to be modified instead, then set MODIFY_NAMED_CONF_DYNAMICALLY to yes. Since it makes not much sense to write the same nameservers to both files MODIFY_NAMED_CONF_DYNAMICALLY has a higher priority then MODIFY_RESOLV_CONF_DYNAMICALLY. Programs which use modify_resolvconf don't need to respect these variables. They should call modify_resolvconf just always.

ACTIONS

modify
    write a new /etc/resolv.conf or /etc/named.conf with the supplied data and create a backup of the old one.

restore
    take a backup of the given service (if it exists) and restore it to the modified file. This might be /etc/resolv.conf or /etc/named.conf itself or another backup which was made in between by any other service. E.g. pcmcia modified /etc/resolv.conf for an ethernet interface and after that ppp modifies it again for a modem connection. If you then eject the pcmcia card but keep the modem connection, the backup made by pcmcia will be restored to the backup made by ppp and leave the /etc/resolv.conf or /etc/named.conf modified by ppp untouched.
    If no extension was given it will remove all other backups of the given service (resolv.conf.saved.by.<service>*).

cleanup
    remove all backups of /etc/resolv.conf and /etc/named.conf while trying to restore the original ones. It does so for both /etc/resolv.conf and /etc/named.conf independently of the settings of the variables in /etc/sysconfig/network/config. If you want to clean up only for one of these then use the --resolv or --named option.

check
    return 0 if /etc/resolv.conf has not been modified dynamically and write a status message to stderr. If /etc/resolv.conf has been modified dynamically, it returns 1 and echoes the text contained in the Info: tag to stderr. br. Note that it always checks /etc/resolv.conf independently of the settings of the variables in /etc/sysconfig/network/config. If you want to check /etc/named.conf then use --named because in certain situations you are interested in the state of exactly one of these configuration files. E.g. if YaST wants to set new definitive values to /etc/resolv.conf, it has to check if /etc/resolv.conf is modified currently and is not interested if /etc/named.conf was changed even if MODIFY_NAMED_CONF_DYNAMICALLY was set.

OPTIONS

-s, --service <service>
    name of the service that requests the modification. This will used for the name of the backup, and it is put into the Modified_by tag of the info header (see example below).

-e, --extension <string>
    appends an additional extension to the backup filename (this can be used by a service to create more than one backup like for different ppp devices)

-p, --process <process>
    name of the daemon that causes the modification (if applicable)

-i, --pid <pid>
    process ID of the daemon that causes the modification (if applicable)

-f, --script <filename>
    some script is used by the daemon to request the modification

-t, --text <text>
    a text written to the informational header that explains why the change was done and how to prevent it in the future. If - is given as <text>, the text is read from stdin.

-l, --searchlist <list of search domains>
    specifies a list of domains, separated by spaces and protected by quotes, to be written to /etc/resolv.conf as searchlist

-d, --domain <domainname>
    the domain to be used

-n, --nameservers <list of nameservers>
    the (space separated and quoted if necessary) list of nameservers to be used

-o, --save_now <filename>
    saves the current /etc/resolv.conf (/etc/named.conf) to the specified file. This may be used if you are interested in the modification after restore or cleanup. Alternatively you can use --save_later when modifying.

-a, --save_later <filename>
    inserts an additional tag into the informational header specifying a filename to use for an backup of the modified configuration file to be done at restore time. Alternatively you can use --save_now when restoring or cleaning up.

-k, --keep
    if used with restore or cleanup it keeps the current (modified) resolver settings.

--resolv
    restores, cleans up or checks /etc/resolv.conf independently of the settings of the variables in /etc/sysconfig/network/config. This variable is ignored with 'modify'.

--named
    restores, cleans up or checks /etc/named.conf independently of the settings of the variables in /etc/sysconfig/network/config. This variable is ignored with 'modify'.

--no_restart
    does not trigger any actions like restarting named or copying /etc/resolv.conf to the chroot environment of postfix.

-v, --verbose
    be verbose

-q, --quiet
    be quiet

-h, --help
    show synopsis

EXAMPLE
This is an example for the /etc/resolv.conf that modify_resolvconf would create: ### BEGIN INFO
#
# Modified_by: dhcpcd
# Backup: /etc/resolv.conf.saved.by.dhclient
# Process: /sbin/dhcpcd
# Process_id: 12345
# Script:
#
# Info: blabla
# ...
#
### END INFO
search suse.de
nameserver 10.10.0.1
nameserver 10.10.0.2

FILES
/etc/resolv.conf
/etc/named.conf

BUGS
save_later does not work properly if restoring one /etc/resolv.conf out of a stack of backups.
Currently modify_resolvconf is dog slow, but this will be enhanced in further versions.

SEE ALSO
resolv.conf(5), named.conf(5)

AUTHOR
Christian Zoz <zoz@suse.de>
Manual page by Peter Poeml <poeml@suse.de> and Christian Zoz <zoz@suse.de>.