man(5)

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

SEE ALSO
npd6(8)

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

AUTHOR
Sean Groarke (sgroarke@gmail.com)