freebsd-skq/usr.sbin/pim6sd/pim6sd.conf.5

.\" Copyright (C) 1999 WIDE Project.
.\" All rights reserved.
.\" 
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\" 3. Neither the name of the project nor the names of its contributors
.\"    may be used to endorse or promote products derived from this software
.\"    without specific prior written permission.
.\" 
.\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\"	KAME Id: pim6sd.conf.5,v 1.10 2000/07/09 17:28:42 itojun Exp
.\"	$FreeBSD$
.\"
.Dd Oct 6, 1999
.Dt PIM6SD.CONF 5
.Os
.Sh NAME
.Nm pim6sd.conf
.Nd config file for pim6sd, PIM-SM daemon for IPv6
.\"
.Sh DESCRIPTION
The
.Nm
configuration file consists of a sequence of statements terminated
by a semi-colon (`;'), each of which specifies how the daemon treats
each interface on the system, specifies some parameters of the PIM
protocol, and requires some special behavior defined by the protocol.
.Pp
Each statement can be constructed by multiple lines.
.Pp
Lines beginning with
.Ql #
are comments.
.\".Pp
.\"Note that
.\".Xr pim6sd 8
.\"works even without the configuration file, although the daemon
.\"will warn that there is no configuration file.
.\"In such a case, the daemon will automatically set the default value
.\"to each configurable parameter.
.\"
.Pp
The following statements can be specified in the configuration file.
.Pp
.Bl -tag -width Ds -compact
.It Xo
.Ic log
.Ar option...
.Ic ;
.Xc
Specify debug messages to be printed out. Each
.Ar option
usually specifies a subset of the messages to be printed.
If an
.Ar option
begins with
.Ic no ,
it means that the set of the messages that are specified by the option
will not be printed. For example,
.Ic `all nomld'
means that all the messages except MLD related ones will be printed.
Valid options are
.Ic mld_proto, mld_timer, mld_member, mld, switch, trace, mtrace, traceroute,
.Ic timeout, callout, pkt, packets, interfaces, vif, kernel, cache, mfc,
.Ic k_cache, k_mfc, rsrr, pim_detail, pim_hello, pim_neighbors, pim_register,
.Ic registers, pim_join_prune, pim_j_p, pim_jp, pim_bootstrap, pim_bsr, bsr,
.Ic bootstrap, pim_asserts, pim_cand_rp, pim_c_rp, pim_rp, rp, pim_routes,
.Ic pim_routing, pim_mrt, pim_timers, pim_rpf, rpf, pim, routes, routing,
.Ic mrt, routers, mrouters, neighbors, timers, asserts,
and
.Ic all .
.\"
.It Xo
.Ic reverselookup (yes \(ba no);
.Xc
Specifies if a hostname for an IPv6 address should be resolved
on logging.
.Ic yes
means a hostname should be resolved, and
.Ic no
means should not.
By default, a hostname is not resolved.
.\"
.It Xo
.Ic phyint Ar interface
.Op disable
.Ic ;
.Xc
Specifies
.Xr pim6sd 8
to ignore the interface even if the interface is multicast-capable.
Note that PIM will be activated on all interfaces by default(including
the case where there is no configuration file).
Interfaces are specified in the form of "name unit", such as
.Ar gif0
and
.Ar ep1.
.\"
.It Xo
.Ic phyint Ar interface
.Op preference Ar preference
.Op metric Ar metric
.Op nolistener
.Ic ;
.Xc
Specifies the preference and/or metric values when sending a PIM
assert message on the interface.
If another optional parameter
.Ic nolistener
is specified,
.Xr pim6sd 8
will not send any MLD packets on the interface.
This option is usually meaningless but will be useful when
MLD messages are noisy (e.g. when debugging) and there is surely no
listner on the interface.
.\"
.It Xo
.Ic default_source_preference Ar preference;
.Xc
Specifies a default preference value when sending a PIM assert message.
Preferences are used by assert elections to determine upstream routers.
Currently
.Xr pim6sd 8
cannot reliably obtain preferences and metrics from the
unicast routing protocols, so a default value may be configured.
The default preference is 1024.
.\"
.It Ic default_source_metric Ar metric;
Specifies a default metric value when sending a PIM assert message.
It is recommended that preferences be set such that metrics are never
consulted. However, default metrics may also be set and will default to
1024.
.\"
.It Xo
.Ic granularity Ar second;
.Xc
Specifies timer granularity in seconds.
The default value is 5.
.\"
.It Xo
.Ic hello_period Ar period Ar coef;
.Xc
.Ar Period
specifies the period in second between 2 hello messages.
.Ar Coef
is the coefficient to determine the hello holdtime;
the holdtime will be
.Ar period
*
.Ar coef .
The default values of the period and the coefficient are 30 and 3.5,
respectively. The default holdtime is 105 seconds as a result.
.\"
.It Xo
.Ic join_prune_period Ar period Ar coef;
.Xc
.Ar Period
specifies the period in second between 2 join/prune messages.
.Ar Coef
is the coefficient to determine the join/prune holdtime;
the holdtime will be
.Ar period
*
.Ar coef .
The default values of the period and the coefficient are 60 and 3.5,
respectively. Consequently, the default holdtime is 210 seconds.
.\"
.It Xo
.Ic data_timeout Ar timer;
.Xc
Specifies the time after which (S,G) state for a silent source will be
deleted.
The default value is 210.
.\"
.It Xo
.Ic register_suppression_timeout Ar interval;
.Xc
.Ar Interval
specifies the interval between receiving a Register-Stop and allowing
PIM Register to be send again.
The default value is 60.
.\"
.It Xo
.Ic probe_time Ar timer;
.Xc
.Ar Timer
specifies the time between sending a null Register and the
Register-Suppression-Timer expiring unless it is restarted by
receiving a Register-Stop.
The default value is 5.
.\"
.It Xo
.Ic assert_timeout Ar interval;
.Xc
.Ar Interval
specifies the interval between the last time an Assert is received and
the time at which the assert is timeout.
The default value is 180.
.\"
.It Xo
.Ic cand_rp
.Op Ar interface
.Op Ic time Ar time
.Op Ic priority Ar priority
.Ic ;
.Xc
Specifies to act as a candidate Rendezvous Point(RP).
It is recommended to specify
.Ic cand_rp
only in typical usage.
All other parameters are optional and will be set automatically.
If an
.Ar interface
is specified,
.Xr pim6sd 8
will search for a global address on the specified interface
and set the address in Candidate RP Advertisements.
An optional parameter
.Ic time
specifies the interval of two succeeding advertisements in seconds.
Its default value is 60.
2.5 *
.Ar time
will be set to Candidate-RP-Advertisement messages.
Another optional parameter
.Ic priority
specifies the priority of the RP.
The default value is 0, which means the highest priority.
.\"
.It Xo
.Ic group_prefix Ar prefix;
.Xc
When acting as a Rendezvous Point(RP),
.Ar prefix
specifies a group prefix that the RP will handle.
.\"
.It Xo
.Ic cand_bootstrap_router
.Op Ar interface
.Op Ic time Ar time
.Op Ic priority Ar priority
.Op Ic masklen Ar masklen
.Ic ;
.Xc
Specifies to act as a candidate bootstrap router(BSR).
It is recommended to specify
.Ic cand_bootstrap_router
only in typical usage.
All other parameters are optional and will be set automatically.
If an
.Ar interface
is specified,
.Xr pim6sd 8
will search for a global address on the specified interface
and set the address in Bootstrap messages.
An optional parameter
.Ic time
specifies the interval of two succeeding bootstraps in seconds.
Its default value is 60.
Another optional parameter
.Ic priority
specifies the priority of the RP.
The default value is 0, which means the lowest priority.
Hash mask length can also be specified by the
.Ic masklen
parametr. Its value,
.Ar masklen ,
must be no less than 0 and no greater than 128.
.\"
.It Xo
.Ic switch_register_threshold Ic rate Ar rate Ic interval Ar interval;
.Xc
Specifies the threshold that a Rendezvous Point(RP) switches to a shortest
path tree, which is valid only when acting as an RP.
.Ic rate
specifies the threshold in bits per second, and
.Ic interval
specifies the interval of checking the rate in seconds.
The default values are 50000 and 20, respectively.
\"
.It Xo
.Ic switch_data_threshold Ic rate Ar rate Ic interval Ar interval;
.Xc
Specifies the threshold that a last hop router switches to a shortest
path tree.
.Ic rate
specifies the threshold in bits per second, and
.Ic interval
specifies the interval of checking the rate in seconds.
The default values are 50000 and 20, respectively.
.El
.\"
.Sh EXAMPLE
.Bd -literal -offset
# phyint gif0 disable;
# phyint ep0 preference 101;
phyint de0 disable;
#
# followings are for a candidate Rendezvous Point, which should usually
# be disabled.
cand_bootstrap_router;
cand_rp;
.Ed
.Sh SEE ALSO
.Xr pim6sd 8
.Sh HISTORY
The
.Xr pim6sd 8
command is developed by Mickael Hoerdt at LSIIT Laboratory.
It is based on IPv4 PIM sparse-mode
.Nm pimd
developed at University of Southern California,
which has also been derived from
.Nm mrouted .
.Nm mrouted
is COPYRIGHT 1989 by The Board of Trustees of
Leland Stanford Junior University.
.Pp
IPv6 and IPsec support based on the KAME Project (http://www.kame.net/) stack
was initially integrated into
.Fx 4.0