Ubuntu Manpage: npd6.conf - configuration file for neighbor proxy daemon ipv6 npd6

NAME

       npd6.conf - configuration file for neighbor proxy daemon ipv6 npd6

DESCRIPTION

This file contains parameters which affect the manner of npd6's operation. The first section contain a
few common parameters - you will need to change these to suit your situation. The second set are less
likely to require changing and will typically work fine at their default value. In fact: if you change
the second set and get it wrong, npd6 may work badly, intermittently or not at all. Leave them alone
unless you have a real reason to change them!

All these parameters can be dauting. Fear not! Probably 95% of the folks who use npd6 have received a
64-bit prefix from their ISP and want to have their box answer neighbor solicitations for the prefix on,
maybe, interface eth0. And that's all they want. So read a bit of General Parameters below and set your
one prefix and one interface and happily leave everything else alone... It'll work great for you.

General parameters
prefix = prefix[/mask]
This defines the prefix which will be matched against received Neighbor Solicitations. It will
often be a /64 supplied by an ISP, but this is by no means mandatory.

Note that leading zeros are not required, but can be used. So
prefix=2a01:0123:0456:0007:
is equivalent to
prefix=2a01:123:456:7:

The prefix does require a terminating colon, e.g.
prefix=2a01:123:456:7:

The /mask value is optional, and often not required. In many cases where npd6 is used, the user
will have received a 64-bit prefix from their ISP. Simply add this as the prefix here and you'll
be good to go!

If the /mask value is not supplied, but the prefix given is not a 64-bit one, then an implicit
mask is used of the prefix's length rounded up to the next 16-bit boundary. e.g.
prefix = 2000:11:22:33:8000::
is implicitly euivalent to
prefix = 2000:11:22:33:8000::/80

If a /mask value is used, then it operates in the traditional (although maybe unintuitive to
some!) maner of an IP mask. For example:
prefix = 2000:11:22:33::/65
would match 2000:11:22:33::0 thru 2000:11:22:33:7fff:ffff:ffff:ffff

Whereas
prefix = 2000:11:22:33:8000::/65
would match 2000:11:22:33:8000::0 thru 2000:11:22:33:ffff:ffff:ffff:ffff

If you understand masks, then they are there and available. If you do not understand masks, just
ignore this.

Finally: a useful shorthand to match any address within a NS on the designated interface is
prefix=0::/0
However its use would be unusual and could lead to some unforseen consequences if not thought
through. Use with care.

interface = [interfacename]
This defines the interface to which we will bind and listen. Note also that this is the interface
which will, by default (see below), have the multicast flag enabled if required too.

It will typically be one of the ethernet interfaces, e.g.
interface=eth0

Note that there is no static limit to how many interface/prefix pairs that can be specified. Also not
fixed is how multiple pairs are configured: you can choose to list the interfaces first, followed by a
list of prefixes. Or alternatively to pair them up in the config file instead. Note however that there
must be an equal number of prefixes as interfaces. Every interface must have a prefix defined for it (if
only a wildcard)

Address blacklisting & whitelisting
listtype = [none|black|white]
This defines the type of "listing" (if any) to be performed: whitelisting, blacklisting or none at
all. What is "listing"? In general, a whitelist ONLY allows items pre-configured on the list to be
permitted. A blacklist allows anything EXCEPT those items pre-configured on the list.

If black or white is specified then you should also then define at least 1 (and as many more as
you require) addrlist and/or exprlist items.

Note also that this config item must be before the addrlist or exprlist items in the config file.

addrlist= <ipv6 address>

e.g. addrlist = 2a01:0123:456:7::22 (All the usual formats are supported.)

Defines the list of addresses to be either white- or black-listed.

exprlist = <expression to match>

e.g. exprlist = (HOST);SEAN=(HOST&0xffff);((SEAN>0x99)&&(SEAN<0x124))

This example will (if black listing) refuse any NS that is for PREFIX::100 up to PREFIX::123. It
any other PREFIX:: value will match. Or if whitelisting, will only allow value in those ranges.

listlogging = [off|on]
If on addresses which match a white/blacklist will be logged (even if debug is not enabled). If
off matches will not be logged (unless debug is in use, when they will be logged regardless)

Default: off

List-type precedence

Note that exprlist values take precedence over addrlist values (if both are specified)

Behaviour with no black- or whitelisting

This is the default mode of operation and likely what most people will want. In this mode (the original
mode before this feature was introduced) any Neighbor Solicitation received with a target address which
matches the prefix will be answered by an appropriate Neighbor Advertisement, irrespective of whether or
not that target actually exists and/or is reachable from here.

Behaviour with blacklisting

This mode of operation modifies how npd6 behaves: when a Neighbor Solicitation is received with a prefix
which matches that configured, before a Neighbor Advertisement is generated in reply the target is
additionally checked against the list of addresses defined. If it matches one of those addresses then the
Neighbor Solicitation is silently ignored and no response generated.

Behaviour with whitelisting

This mode of operation modifies how npd6 behaves: when a Neighbor Solicitation is received with a prefix
which matches that configured, before a Neighbor Advertisement is generated in reply the target is
additionally checked against the list of addresses defined. Only if it matches one of those addresses is
a Neighbor Solicitation is generated in response.

Special parameters
collectTargets = amount
Optionally, npd6 can record a list of targets received in the incoming Neighbor Solicitations, to
which it has replied. These can be displayed in the defined log by sending a USR2 signal npd6.
e.g. kill -USR2 <pid of npd6>

This parameter defines a limit to the number of addresses recorded. If the value is zero, then the
feature is disabled. This is the default behaviour. The parameter should be set to a suitably
large but sane value. The only significant overhead is memory (for storing the addresses) Given
the address space of IPv6 and the possibility of receiving very many different target addresses to
not provide a ceiling to this feature would potentially open npd6 up to a denial-of-service based
upon memory depletion.

In a typical situation, where a network might expect to receive Neighbor Solicitations for several
dozen devices, there's likely no harm in setting this to 100 or 1000. Just don't set it at
10,000,000 without thinking first. Memory is only allocated as-required - if you do set a high
limit, npd6 does not preallocate the memory, but only use it as and if required.

linkOption = false|true
Normal RFC-compliant behaviour requires that if npd6 is replying to a multicast Neighbor
Solicitation it must include the Target Link-Layer option in any reply. However if replying to a
unicast Neighbor Solicitation this option is not required. Hence it is normally not used unless
enabled here by changing the this to true

Default: false

ignoreLocal = false|true
If npd6 receives a Neighbor Solicitation for the global address of the interface to which it is
bound, if set to true npd6 will ignore and not reply - this is since ordinarily the kernel will
itself automatically respond to such a situation.

If changed from the default and set to false then such Neighbor Solcitations will be responded to
- possibly resulting in duplicated Neighbor Advertisements.

Default: true

routerNA = false|true
Normal RFC-compliant behaviour requires that outgoing Neighbor Advertisements have the ROUTER flag
set in them. This will be done unless disabled by changing this to false.

Default: true

maxHops = [0-255]
Outgoing Neighbor Advertisements will normally have their maximum hop value set to 255. if set
incorrectly no anomaly in the operation of npd6 will be seen - however Neghbor Advertisements
generated by npd6 may be silently ignored by the receiving device. Do not change without good
reason!

Default: 255

pollErrorLimit = [0-255]
This is to cater for situations when an interface goes bad for a short time, but comes back in the
end. e.g. bouncing an interface, or during boot-up when things might take a second or three longer
than expected to be ready and available.

Set to 0 to disable the mechanism completely.

Given the nature of the underlying mechanisms, if an interface goes away and does not come back,
this threshold strictly speaking is the minimum number of poll failures we will wait for before
permanently failing. However practically speaking, this value represents the minimum period in
seconds which we will wait before taking this action. The maximum period is potentially twice this
value.

Note that if this value is set higher than 30, the mechanism may not operate as expected! This is
implementation dependent. Best left alone, to be honest... 20 is a sensible default value!

Default: 20

BUGS

       No known bugs - Please report them to npd6Project@gmail.com

AUTHOR

       Sean Groarke (sgroarke@gmail.com)

1.0.0                                            03 January 2013                                          man(5)

NAME

DESCRIPTION

SEE ALSO

BUGS

AUTHOR