dhcp-fwd - Man Page

dhcp-fwd [-n] [-N] [-d] [-v] [-h] [-c config_file]

dhcp-fwd starts a DHCP forwarding agents which relays DHCP messages between subnets with different sublayer broadcast domains.

When called without arguments, it reads its configuration from /etc/dhcp-fwd.conf and forks itself into background. An alternative configfile can be given by the -c option; the forking can be prevented with the -n switch. There exists a -d option which is indented for debugging purposes and prevents forking too. Currently it is just an alias for -n.

Although the program must be started as root, it will drop its privileges and go into a chroot-jail after finishing the initialization.

-n

Prevents daemon from going into background after initialization. This option may be useful when using advanced init-concepts like minit (http://www.fefe.de/minit/).

-N

Like -n but program sends a SIGSTOP signal to itself when initialization has been finished.  This is interpreted e.g. by the upstart init system.

-d

Turns on debugging mode and prevents forking; currently it is just an alias for -n.

-c config_file

Specifies the configfile to use; the default is /etc/dhcp-fwd.conf.

-v

Shows version

-h

Shows help

The default location of the configfile is determined at compilation-time and can be overridden by using the -c option. When an option needs a boolean parameter, the keywords true, false, 0, 1, yes and no are possible values.

Within the configfile the following options MUST be set:

user username|uid

The program setuid()'s to the given user after finishing its initialization. The parameter must be an alphanumeric username or a numeric uid.

group groupname|gid

The program setgid()'s to the given group after finishing its initialization. The parameter must be an alphanumeric groupname or a numeric gid.

chroot path

The program goes into this directory and calls there chroot() after finishing its initialization.

pidfile filename

The file where the pid of the daemon will be written into.

Beside the mandatory options above, the following options are possible:

ulimit resource limit

Sets a maximum limit for the given resource by calling setrlimit() appropriately. Possible values for resource are stack, data, core, rss, nproc, nofile, memlock, as and (if supported by your OS) locks. For the meaning of this values see setrlimit(2).

limit may be plain unsigned number, a number followed by 'k' (*1000), 'K' (*1024), 'm' (*1000k), 'M' (*1024K) or '-1' to remove the limit for this resource.

logfile filename

Specifies the file where messages will be stored. This file is located relatively to the directory where dhcp-fwd was started and not to the directory given at the chroot option.

if ifname has_clients has_servers allow_bcast

Declares an interface and sets parameter of the network topology. When an interfacename is used in one of the other options, it must have been declared by if already.

ifname is the name of the interface as being used e.g. by ifconfig also (e.g. eth0).

has_clients and has_servers tell if messages from clients or servers can be expected on this interface. BOOTREQUESTs are assumed to be client- and BOOTREPLYs are assumed to be server-messages. Unexpected packages will be dropped away.

allow_bcast is/was an experimentell features and will be disappear probably. When not set, the interface will not send packages to IP-broadcast addresses. This affects messages to clients only; when specifying a bcast-server, this option will be ignored.

ports ifname client-port server-port

Declares the ports which are used on the specified interface ifname for client resp. server functionality.

dhcp-fwd acts as client only, when the has_servers flag has been set and sends from client-port then. Interface will be listen on server-port when the has_clients and/or has_servers flags of the interface have been set.

Omitting this option for an interface or using a value of "0" for the port arguments uses default values.  These are port 68/udp (bootpc) for client-port and port 67/udp (bootps) for server-port by default.

NOTE: This option exists to avoid conflicts with already running dhcp servers, clients or relay agents which do not bind to specific interfaces.  The DHCP/BOOTP protocol relies on the 67/udp + 68/udp ports and you have e.g. to configure iptable rules which rewrite your custom port numbers to the expected ones.

See Bugs below for further restrictions.

name ifname agent-id

specifies the RFC 3046 agent-id for the given interface. When not used explicitly, the interfacename will be assumed as the agent-id.

ip ifname ip

assigns the ip to be used in the giaddr field. By default to IP of the interface will be assumed but when having multiple IPs for one interface this option may be usefully.

Attention: This IP will not be used in the IP-layer; this means that the UDP packet sent to the server will contain the IP assigned by the system. To setup this address, usual SNAT rulesets in a local packetfilter are recommended.

server type info

Defines the DHCP server to be used. The following types are supported:

server ip address [interface]

address is a dotted IP-address and the optional interface the name of an interface. Please note that mixing declarations without an interface parameter and such ones with this parameter will fail.

server bcast interface

the DHCP server with be assumed at interface interface and contacted with broadcast messages.

suboption interface code value

sets a relay-agent option. The following values for code are supported:

suboption interface 2 agent-id

Sets the agent remote id; this is the same as "name interface agent-id".

suboption interface 5 ip

Set the RFC3527 link selection.

suboption interface 11 ip

Set the RFC5107 server identifier..

compathack type hack

Sometimes, new versions of dhcp-fwd will contain changes/fixes which might break existing installations. To restore old behavior, compatibility hacks can be activated.  These hacks are specified by the R hack integer parameter.  See the NEWS file for changes are their corresponding R hack value.

For a sample configuration file see the contrib/dhcp-fwd.conf template in the source-tarball.

It is possible to use $VAR style variable expansion for path, file and interface names, and for ip addresses.  Value of $VAR will be taken from the corresponding environment variable which must be defined. Quoting of leading `$´ characters is possible by prepending a single backslash.

Examples:

pidfile $PIDFILE

if $IFACE t t t

ip $IFACE $IP

The ports set up by the ports configuration option are used for binding sockets only.  The default DHCP port numbers (67 + 68) appear in the UDP headers of the relayed DHCP responses.

/etc/dhcp-fwd.conf

configuration file

/usr/sbin/dhcp-fwd

executable

RFC 2131, 2132, 3046

Enrico Scholz <enrico.scholz@ensc.de>