bfdd-control(8)

NAME
bfdd-control - control utility for bfdd-beacon(8)

SYNOPSIS
bfdd-control [ options ] command

DESCRIPTION
bfdd-control is a control and configuration application for bfdd-beacon(8). It is part of the OpenBFDD package.

OPTIONS
The optional options parameter can be one or more of the following:

--altport
    Causes the "alternate" communications port on 127.0.0.1 to be used for connecting to bfdd-beacon(8). This can be used if there is a problem with the primary port. It could also be used to keep the main port free for normal control if commands are being sent repeatedly in a loop, such as a continual "monitoring" script. This is provided for backwards compatibility purposes. The --control statement is the preferred method for setting the communications channel.

--control=ip:port
    Sets the communication channel to use for communicating with bfdd-beacon. This should match one of the --control options used to start bfdd-beacon(8). This option may only appear once, and may not be used in conjunction with --altport. If neither this, nor --altport, is supplied, then the default communication channel is used.

COMMANDS
The command parameter consists of a command to send to bfdd-beacon followed by one or more parameters for that command. The commands are:

version
    Displays the version number of this utility as well as the version of the current running bfd beacon, if it can be contacted.

stop
    Causes bfdd-beacon to exit.

load path
    Runs all commands in the file specified by path. The file should have each command on its own line. Any line beginning with # is considered a comment line, and will be ignored.

allow ip
    Allows incoming packets from the given ip address. This allows BFD sessions to be established if there is an active BFD service running on the given ip. No session will be created until packets are received from the remote system. The beacon will act in passive mode for these sessions.

connect ip-pair
    Starts an active session between the two ip addresses specified in ip-pair. A session will be created immediately. If there is already a session with the given ip-pair addresses then it is switched from passive to active.

block ip
    Blocks any new connections from being established from the given ip address. Existing sessions with this ip will not be affected. By default all ip addresses are blocked.

log (level (loglevel | list) | type (logtype  (yes | no ) | list))

    level
        Sets logging to one of a set of predefined loglevel values. Use the command log level list to get a list of all available levels. Some of these include none, minimal, normal, detailed, dev and all. The all level will produce a lot of logging and is not suitable for a production situation. The default level at startup is normal.

    type
        Enables or disables specific log types. Use the command log type list to get a full list of logtype values.

log timing (yes | no )
    Enables or disables extended time logging. This will add a nanosecond timestamp to each message, in addition to the normal timestamp. The default is off.

status [(id | ip-pair | all) [level level] [[no]compact] [brief]]
    Displays stats on one or all of the sessions. If no parameters are given then a brief compact level 1 summary of all sessions will be displayed, including their id values. If id or ip-pair is supplied then the status of the specified session will be displayed. If all is used, then information for all sessions will be displayed. level level, where level is an integer, can be used to control the detail that is displayed. The default level is 1. brief will cause certain values to be displayed as codes, or in shortened form, and will not use thousands separators for large numbers. compact will cause the stats for each session to be displayed on a single line. nocompact will place each stat on its own line (this is the default). The items returned in the status are documented in the STATUS ITEMS section of this document.

session (id | ip-pair | all) state stateval [diagnostic]
    Changes the state of the session specified by id or ip-pair, or all sessions. stateval Can be one of the following:

    down
        Forces the session into the "Down" state, and holds it there. The session continues to communicate with the remote session, but the local state remains "Down". diagnostic is an optional integer diagnostic code (as defined in the bfd specification.) The default is 5 ("Path Down")

    admin
        Forces the session into the "AdminDown" state, and holds it there. The session continues to communicate with the remote session, but the local state remains "AdminDown". diagnostic is an optional integer diagnostic code (as defined in the bfd specification.) The default is 7 (Administratively Down")

    up  Allows the session to transition normally out of its current state. Used to end a down or admin hold.

session (id | ip-pair | all) (kill | reset | suspend | resume)
    Used to modify or remove a session specified by id or ip-pair, or all sessions. The action depends on the parameter as follows:

    kill
        Immediately deletes the session. Note that this does not prevent a new passive session from being immediately created if the allow command was used for the remote ip address. Use the connect command to reestablish an active session, if desired.

    reset
        Immediately deletes the session. If the session was an active session then a new active session is created. If the session was a passive session then it will listen for control packets from the original ip address, and will create a session when packets are received, unless the block command has been issued to block the remote ip address.

    suspend
        Prevents the session from sending any packets to the remote session, simulating a unidirectional link failure. This is used primarily for debugging purposes.

    resume
        Resumes sending packets after a previous suspend. If the session is not suspended then this has no effect.

session (id | ip-pair | all | new) set item value
    Used to set certain attributes for the session specified by id or ip-pair, or all sessions, or for new sessions. If new is specified then the setting applies to any future sessions that are created, but no current sessions will be affected. Some of the setting use a timeval for value. A timeval should be an integer, followed by a space, followed by 's' for seconds, 'ms' for milliseconds (1/1,000th of a second), or 'us' for microseconds (1/1,000,000th of a second.) The item parameter can be one of the following:

    mintx
        Sets the "Desired Minimum Transmit Interval" that the local session sends to the remote session in the control packet. When the session is up, the rate at which we send packets to the remote system is (approximately) the larger of this value, and the "Required Minimum Receive Interval" received from the remote session. The value parameter should be a timeval as described above. 0 is not allowed.

    minrx
        Sets the "Required Minimum Receive Interval" that the local session sends to the remote session in the control packet. The rate at which we expect to receive packets from the remote system is (approximately) the larger of this value, and the "Desired Minimum Transmit Interval" received from the remote session. The value parameter should be a timeval as described above. 0 seconds is an allowed value, and indicates that we do not wish to receive any periodic control packets. However, 0 is not supported properly on all remote BFD implementations, and should be used with caution.

    multi
        Sets the "Detection Multiplier" that the local session sends to the remote session in the control packet. This is (approximately) the number of periodic packets, from this session to the remote session, that can be lost before the remote system declares the link down due to timeout. The value parameter should be number between 1 and 255.

    cpi Sets the value of the "Control Plane Independent" (C) flag that the local session sends to the remote session in the control packet. This effects how the remote system handles the "Down" and "AdminDown" states. The exact implications of this flag are up to the remote system. The value parameter should be yes or no.

    admin_up_poll
        Enables or disables a workaround that prevents rapid Up->AdminDown->Up from taking a long time to come back Up. The workaround is needed (at least) for JUNOS8.5S4. See the wiki for more details. The default is enabled. The value parameter should be yes or no.

PARAMETERS
Some of the parameters used in the COMMANDS section require some additional explanation.

id  This parameter describes a locally maintained identifier for a session. This id is primarily used as a convenient way to identify sessions when using bfdd-control. Note that this id is not the same as the LocalId used to identify the session to the remote system. Passive sessions can be destroyed after a timeout period. If they are later reestablished they will have a new id. For this, and other, reasons, it may be preferable to use an ip-pair when managing sessions in an automated way.

ip  This parameter describes an ip address. An IPv4 or IPv6 address may be supplied. An IPv4 address muse use dotted quad notation, in the form: "ddd.ddd.ddd.ddd" An IPv6 address can use full notation, in the form: "hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh" or shorthand notation, such as: "hhhh:hhhh::hhhh". Dotted-quad notation may be used for Ipv6 addresses, to specify the final 32 bits. For example ::ffff:192.0.2.128 is equivalent to ::ffff:c000:0280. Link-local addresses must also be followed by an interface name, using the form: "hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh:hhhh%ifname", where ifname is the name of the interface to which the link local address applies. An interface may only be specified for link-local addresses. Of course, shorthand notation may also be used with link local addresses.

ip-pair
    This parameter describes a pair of ip addresses. It should take the form "local ip remote ip", where ip is an ip address as described above. The "local ip" describes the ip address on the local system that will be used for the bfd session. The "remote ip" describes the ip address on the remote system that will be used for the bfd session. The local and remote addresses may be specified in any order in an ip-pair.

STATUS ITEMS
The status command returns a number of status items. Below is a brief description of some of these items. This assumes an understanding of the Bidirectional Forwarding Detection (BFD) protocol and refers to items in BFD Base Specification the RFC5880 at http://www.rfc-editor.org/rfc/rfc5880.txt . Note that some items are only available at higher status levels.

id  The id of the given session. This id is only used to refer to the session when using bfdd-control commands. This is not used in the actual BFD protocol and is not the same as LocalId

local
    The local ip address used to send and receive packets for this session. This may be followed by (active) or (passive) depending on what role the session is taking.

remote
    The remote ip address used to send and receive packets for this session.

LocalState
    The local Session State (bfd.SessionState in outgoing control packets.) This is followed by the Local Diagnostic value (bfd.LocalDiag) which gives the reason for the most recent state change. This item may also include Forced if the current state is being held using the bfdd-control session state command. This item may also include Suspended if the session is suspended.

RemoteState
    The remote Session State (the "Sta" field in the most recently received control packet.) This is followed by the Remote Diagnostic value (the "Diag" field in the most recently received control packet) which gives the reason for the most recent remote state change.

LocalId
     The Discriminator used to identify this session in packet exchanges with the remote system (bfd.LocalDiscr, and the "My Discriminator" field in outgoing packets.)

RemoteId
    The Discriminator used to identify the remote session in packet exchanges with the this system (bfd.RemoteDiscr, and the "My Discriminator" field in incoming packets.)

Time
    The amount of time spent in the current state. At higher status levels this may include the time spent in the 4 most recent states.

CurrentTxInterval
    The interval between sending scheduled control packets. This value is calculated based on a number of other settings.

CurrentRxTimeout
    The Detection Timeout after which, if no packets are received from the remote system, the session is put into the Down state. This is based on the larger of RemoteDesiredMinTx and LocalRequiredMinRx multiplied by RemoteDetectMulti.

LocalDetectMulti
    The approximate number of scheduled packets that the remote system can't receive before it will declare the session Down. (bfd.DetectMult and the "Detect Mult" field in outgoing packets.)

LocalDesiredMinTx
    The lowest interval (highest rate) at which we can (want) to send packets. (bfd.DesiredMinTxInterval and "Desired Min TX Interval" in outgoing packets.) The remote system will expect to receive packets at intervals of, approximately, the larger of this and RemoteRequiredMinRx. When the session is not Up, then the normal value may not be used. In that case the value that will be used when the session is up will be displayed in parenthesis and marked with def. This value can be changed using the bfdd-control session set mintx command. In some cases the new value is not actually used until the remote system acknowledges the change. In these cases the pending value will be displayed in parenthesis and marked with pending.

LocalRequiredMinRx
    The lowest interval (highest rate) at which we can (want) to receive packets. (bfd.RequiredMinRxInterval and "Required Min RX Interval" in outgoing packets.) The remote system will send periodic control packets at intervals of, approximately, the larger of this and RemoteDesiredMinTx. This value can be changed using the bfdd-control session set minrx command. In some cases the new value is not actually used (for timeout detection) until the remote system acknowledges the change. In these cases the pending value will be displayed in parenthesis and marked with pending.

RemoteDetectMulti
    The approximate number of scheduled packets that the local system can't receive before it will declare the session Down. ("Detect Mult" field of the last incoming packet.)

RemoteDesiredMinTx
    The lowest interval (highest rate) at which the remote system can to send packets. ("Desired Min TX Interval" in the most recently received packet.) Used in calculating CurrentRxTimeout.

RemoteRequiredMinRx
    The lowest interval (highest rate) at which the remote system can receive packets. ("Required Min RX Interval" in the most recent incoming packet.) Used in calculating CurrentTxInterval.

NOTES
Currently the program only exits with an error if it fails to make or maintain a connection with bfdd-beacon(8). If the beacon rejects the command, or the command fails to execute, this still exits with an exit code of 0 (success). This could change in the future.

BUGS
No know bugs at this time.

SEE ALSO
bfdd-beacon(8)

AUTHOR
Jake Montgomery for Dynamic Network Services, Inc.

COPYRIGHT
Copyright (c) 2010-2014, Dynamic Network Services, Inc.