Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

IP PoolBot CLI Configuration Statements

 

This topic provides an overview of configuration commands, including syntax and option descriptions.

auto-reclamation (IP PoolBot)

Syntax

Hierarchy Level

Description

Configure IP PoolBot to automatically drain pools and recover their addresses for use in other pools. When you enable auto-reclamation, IP PoolBot requests monitoring updates for the domain every 5 seconds.

Note

You must configure at least one option, even if it is with the default value, to enable automatic reclamation.

Note

IP PoolBot cancels all pending drain and recovery transactions when you remove auto-reclamation from the configuration.

Options

active (always | window)Specify when auto-reclamation is active.
  • always—IP PoolBot always evaluates pools that are critical or idle to determine whether to initiate reclamation.

  • window—IP PoolBot evaluates pools for reclamation only during the time window that you define with the window-start and window-duration options. If either of these options is set to 0, IP PoolBot acts as if you configured the always option.

    Note

    A pool will be reclaimed after the window expires if both of the following occur:

    • The pool begins draining but does not complete it during the window. This means that the pool still has some addresses and is therefore not idle.

    • The pool continues to drain and becomes idle after the window expires.

Default: always

override-free-address-thresholdSpecify that a drain action can proceed even if the result is that the pool domain drops below its free-address threshold. One case for using this option is when you have many pools that are only partially used. The pool domain is fragmented in this situation. Draining the pool defragments the domain by consolidating the used addresses. Then IP PoolBot adds a new empty pool at the end of the domain.
reclaim-pool-domain-head (always | never | best-alternate)Specify what happens when the pool domain head triggers reclamation.
  • always—The pool domain head is drained and its addresses are reclaimed.

  • best-alternate—All other pools in the domain are examined for reclamation. IP PoolBot determines the reclamation weight of each pool, including the domain head. It compares the weights of the other pools to that of the domain head. The pool with the closest match is selected to be drained and reclaimed.

  • never—The pool domain head is not drained and its addresses are not recovered. The domain head pool is placed in the critical pool, but IP PoolBot does not initiate a drain action. This option is useful in DHCP deployments where the prefix used in the first address pool must be a match with the giaddr.

Default: never

used-address-threshold-age minutesSpecify how long a pool must be under the used-address threshold (and therefore in critical state) before IP PoolBot is triggered to drain the pool. By default, the pool is eligible for draining as soon as it drops below the threshold. If the number of used addresses in the pool rises above the threshold (the pool moves to nominal state) before it triggers the drain, the pool is no longer eligible for draining unless it later returns to the critical state. Changing this value has no effect on existing pools.
Best Practice

A value greater than 0 gives the pool a buffer period during which it might rise back above the used-address threshold and not need to be drained.

Default: 1

Range: 0 through 60

window-duration minutesSpecify how long the window is open from the window-start time for IP PoolBot to evaluate pools and initiate reclamation.

Default: 60

Range: 15 through 720

window-start timeSpecify when the window opens for evaluation and reclamation. This option requires the active option to be set to window. You specify the time using a 24-hour clock in one of the following ways:
  • HH:MM+hhmm—Specify the time and indicate the positive offset from local time. For example, if you specify 15:21+01:00, the start time is 16:21, local time.

  • HH:MM-hhmm—Specify the time and indicate the negative offset from local time. For example, if you specify 15:21-01:00, the start time is 14:21, local time.

entity (IP PoolBot)

Syntax

Hierarchy Level

Description

Define attributes of the managed BNGs, also known generically as entities or devices.

Options

entity ip-addressSpecify the primary IPv4 address of the BNG. This address must be usable regardless of the Routing Engine redundancy state of the router, so it must be a master-only management address.
entity-name nameAssign a name for the managed BNG that is unique across the domain. For example, this might be a fully qualified domain name (FQDN).
monitoringConfigure attributes for monitoring the pool domains on the managed BNG.
  • profile profile-nameSpecify the name of a profile that defines attributes associated with the jnprHealthBot plug-in that interacts with HealthBot to monitor the managed BNGs.
provisioningConfigure how IP PoolBot provisions addresses on the BNG.
  • install-routesEnable IP PoolBot to provision a static discard route for the pool prefix each time IP PoolBot adds a new prefix to the pool domain. When install-routes is true, you can optionally use the route-tag option in the partition configuration to specify a tag for the discard route created by the BNG.

    Default: true

  • profile profile-nameSpecify the name of a profile that defines attributes associated with the jnprNETCONF plug-in that interacts directly with the managed BNGs.

See pool-domain (IP PoolBot) for information about configuring the pool domains on a managed BNG.

inet-pool (IP PoolBot)

Syntax

Hierarchy Level

Description

Configure how IP PoolBot partitions its global pool of IPv4 addresses, from which it allocates addresses to individual BNG pool domains. The inet-pool consists of multiple partitions that you create to define allocation contexts. You configure multiple root prefixes for each partition. You can specify the minimum and maximum size of root prefixes that are valid for the partition. You specify the smallest subnetwork that IP PoolBot can subdivide from a particular root prefix. IP PoolBot subdivides the root prefixes and allocates the resulting subnetworks to individual pool domains as needed to supplement the domain’s available addresses.

Options

free-prefix-utilization percentageSet the minimum threshold percentage for unallocated prefixes in the partition. When the percentage drops below this value, a warning message is generated to indicate that the partition is running low on available addresses. The notification is only informative and triggers no other actions.

Default: 10

Range: 0 through 100

max-prefix-length max-subdivided-prefix-lengthDefine the smallest subnetwork that IP PoolBot can subdivide from the specified root prefix. As the prefix length increases, the size of the subnetwork decreases.
max-prefix-len max-root-prefix-lengthSet an upper limit on valid prefix lengths for the root prefixes in this partition. This upper limit defines the root prefix with the fewest host addresses to apportion. As the prefix length increases, IP PoolBot can subdivide fewer subordinate prefixes from the root prefix.

The max-prefix-len value must be greater than or equal to the min-prefix-len. Otherwise , IP PoolBot does not add the prefix to the partition.

Default: 24

Range: 1 through 31

min-prefix-len min-root-prefix-lengthSet a lower limit on valid prefix lengths for the root prefixes in this partition. This lower limit defines the root prefix with the most host addresses to apportion. As the prefix length decreases, IP PoolBot can subdivide more subordinate prefixes from the root prefix.

The min-prefix-len value must be less than or equal to the max-prefix-len. Otherwise , IP PoolBot does not add the prefix to the partition.

Default: 8

Range: 1 through 31

partition partition-nameSpecify the name of a partition that defines an allocation context. The partition contains root prefixes from the centralized address pool.
root-prefix prefix/prefix-lengthSpecify a root prefix for the partition. IP PoolBot subdivides subnetworks from this root to provision addresses for a BNG’s pool domains. The root prefix length must be within the range defined by the values of the partition-level min-prefix-len and max-prefix-len options. You typically configure more than one root prefix per partition.
reserved-prefix prefix/prefix-lengthSpecify a subnetwork that cannot be allocated from this partition. You can optionally qualify the reservation by restricting it to a specified BNG or even to a specified pool domain on that BNG.
  • entity-ip ip-addressSpecify the IP address of a managed BNG for which the prefix is reserved.
  • pool-domain domain-nameSpecify a pool domain on the managed BNG for which the prefix is reserved. Pool domain names must be unique within a given managed BNG.
route-tag tagSpecify a route tag metric that the router associates with the route when it creates a static discard route for the prefix.
Note

This option requires that the install-routes option is true for the relevant entity.

pool-domain (IP PoolBot)

Syntax

Hierarchy Level

Description

Configure pool domains on the managed BNG. Each pool domain corresponds to a linked address pool on the router. The pool domain determines the allocation context. It specifies a partition from which prefixes are allocated, and suggests an address to guide the IP PoolBot to select the desired prefix. It also establishes the address utilization thresholds that HealthBot monitors to trigger address provisioning.

Note

Do not change configurations directly on a BNG for an address pool that IP PoolBot is managing as a pool domain.

IP PoolBot will not detect these changes unless it subsequently loses its connection to the BNG and then reconnects. Then the discovery process will detect the changes.

When you configure IP PoolBot to manage a pool domain, you should consider IP PoolBot to be the exclusive manager of that domain. You should use only IP PoolBot to make any configuration changes to the pool domain.

Options

allocationConfigure the behavior for address allocation and allocation monitoring.
  • excluded-address ip-addressSpecify an address that IP PoolBot excludes when it allocates addresses to the pool domain.
  • max-successive-allocations numberSpecify how many allocations IP PoolBot makes in response to a given critical alarm for the free-address threshold.

    Default: 3

    Range: 1 through 100

  • preferred-prefix-len lengthSpecify the size of the prefix that you want IP PoolBot to provision for the pool domain when the pool domain approaches address depletion. This point is signaled when the number of free addresses in the domain drops below the free-addresses-threshold.

    Default: 24

biasConfigure attributes that influence how IP PoolBot allocates addresses for the pool domain.
  • address-hint ip-addressSpecify an address to guide the allocation for the pool domain. IP PoolBot checks for a root prefix that includes this address. Then it uses the preferred-prefix-len to find the subnetwork that most closely matches the address hint. If no matching subnetwork in the root prefix is available for allocation, then IP PoolBot checks other root prefixes in the partition for a prefix to allocate.
  • partition partition-nameSpecify the name of the partition from which IP PoolBot must allocate addresses to the pool domain.
entity-configConfigure attributes that enable IP PoolBot to map the pool domain on the BNG to the BNG’s configuration.
  • client-type (dhcpv4 | other)Specify the client type that the BNG assigns addresses to from the linked address pool. If you specify dhcpv4, IP PoolBot includes a DHCPv4 attributes stanza in the configuration it sends to the BNG for each provisioned pool to support packet forwarding for DHCP subscribers. In this case, IP PoolBot uses the .1 address for the allocated prefix as the DHCP local server address on the BNG and adds this address to the local loopback interface configuration.

    Default: other

  • local-loopback-interface lo0.logical-unit-numberSpecify the local loopback interface. During pool provisioning, IP PoolBot configures the first address from the prefix range on the local loopback interface.
  • network-instance routing-instance-nameSpecify the routing instance where the linked address pool represented by the pool domain is located.
    Note

    If you change the value for the routing instance name after committing the configuration, this action triggers a modification to the HealthBot playbook and can cause a temporary outage in monitoring.

    Note

    All routing instances are expected to be in the default logical system.

    Default: default

  • pool-head nameSpecify the name of the pool head, which is the first pool of an existing linked address pool that is represented by the pool domain. IP PoolBot needs this name in the configuration so that it can follow the links during the discovery process to identify the rest of the pools in that linked address pool.

    If you change the value for the pool head name after committing the configuration, this action triggers a modification to the HealthBot playbook and can cause a temporary outage in monitoring.

    Note

    Do not use this statement if you intend for IP PoolBot to create a new linked address pool for the domain.

    If you do not specify a name here, IP PoolBot creates a pool head in the following format: jnpr-ipb-pool-domain-name-000. When IP PoolBot subsequently creates more pools for the domain, it simply increments the sequence number to name each pool. For example, the second pool will be jnpr-ipb-pool-domain-name-001, the third pool will be jnpr-ipb-pool-domain-name-002, and so on.

family inetSpecify the IPv4 address family for prefixes in the pool domain. IP PoolBot supports only the IPv4 address family.
monitoringSet attributes for monitoring how a pool domain and the pools within a pool domain are using addresses. Thresholds for free (available) and used (allocated) addresses establish the points at which HealthBot generates alarms to notify IP PoolBot of the state of utilization for pools and the pool domain. The reporting interval determines how frequently HealthBot checks address utilization and reports it to IP PoolBot.
Note

If you change the values for the free-address threshold or used-address threshold after committing the configuration, this action triggers a modification to the HealthBot playbook and can cause a temporary outage in monitoring.

  • free-addresses-threshold free-address-countSet the number of free addresses in the pool domain that specifies the threshold below which HealthBot generates a critical alarm for the pool domain. The alarm triggers IP PoolBot to provision more addresses for the pool domain. The count is the sum of all free addresses across all the individual pools in the domain.
  • reporting-interval seconds(Optional) Set the interval at which HealthBot checks the pool domain pools for address utilization and reports the results.
    Note

    This value is currently ignored. Instead, HealthBot checks pools at a fixed interval of 5 seconds.

    Default: 5

    Range: 5 through 300

  • used-address-threshold used-address-countSet the number of used addresses that defines the threshold for critical and nominal alarms for the pools in the domain.
    • When the number of used addresses in a pool drops below the threshold, HealthBot generates a critical alarm, indicating to IP PoolBot that a specific pool has more addresses than it needs and is suitable for address reclamation.

    • When the number of used addresses in a pool rises above the threshold, HealthBot generates a nominal alarm, indicating to IP PoolBot that the pool is appropriately using addresses and is not suitable for address reclamation.

    When the number of used addresses is 0, the pool is idle, which causes HealthBot to generate an idle alarm.

    Default: 10

pool-domain domain-nameSpecify the name of the pool domain that corresponds to a linked address pool configured on the BNG. The name of the domain must be unique within the BNG.

profiles (IP PoolBot)

Syntax

Hierarchy Level

Description

Define the attributes associated with IP PoolBot plug-ins. You apply profiles to BNGs in the entity configuration. The attributes are then conveyed to the plug-in when IP PoolBot initializes.

Options

liveness(jnprNETCONF profile only) Specify how the jnprNETCONF plug-in manages the connectivity state with the managed BNGs when a connection fails.
  • initial-retry-interval secondsSpecify how long the plug-in waits after detecting a failure before it attempts to reconnect to the BNG. The interval doubles after each subsequent attempt. For example, using the default value of 3 second for the first attempt, the plug-in then waits successively 6 seconds, then 12 seconds, and so on until an attempt is successful or all retries have been used.

    Default: 3

    Range: 1 through 300

  • max-retries numberSpecify how many attempts the plug-in makes to reconnect to a BNG before declaring it to be unreachable. Thereafter, the plug-in continues attempting to reconnect forever, but the retry interval remains fixed at the calculated value used for the max retry attempt.

    Default: 8

    Range: 1 through 16

manager-address ip-address(jnprHealthBot profile only) IPv4 address of the manager.
other-plug-in-name nameSpecify the name of an external plug-in’s executable file. Use this option only with the other plug-in name option.
Note

This option is used only for internal test purposes.

plug-in-nameSpecify the name of the plug-in executable file (.py) for the profile’s plug-in.
  • jnprHealthBotPlug-in that communicates with the external manager, HealthBot, which in turn communicates with managed BNGs for telemetry and monitoring.
  • jnprNETCONFPlug-in that communicates directly with managed BNGs for provisioning and deprovisioning.
  • otherPlug-in that is used only for external plug-ins for internal test purposes. Use this option only with the other-plug-in-name plug-in name option.
plug-in-typeSpecify the type of the plug-in associated with the profile.
  • managerThe plug-in interacts directly with an external manager that in turn directly monitors the managed BNGs. jnprHealthBot is a manager type plug-in.
  • entityThe plug-in interacts directly with the managed BNGs. jnprNETCONF is an entity type plug-in.
port port-numberSpecify the destination port number on the BNG. For provisioning profiles, this is the port where the BNG listens for NETCONF connections from IP PoolBot. For monitoring profiles, this is the port where the BNG listens for REST API connections from HealthBot.
secretsSpecify access credentials that the plug-in needs to access the BNG or external manager.
  • For jnprNETCONF, these are the credentials needed to access the NETCONF/ssh interface on the managed router.

  • For jnprHealthBot, these are the credentials needed to access HealthBot’s REST interface.

  • password stringString of characters that must consist of at least 5 characters from the following set:

    [a-zA-Z0-9!@#$%^&*()]

    Range: 5 through 128

  • username nameString of characters that must consist of 1 character from the set [a-zA-Z] followed by from 3 to 63 characters from the set [a-zA-Z0-9-_].

    Range: 4 through 64

telemetry-port port-number(jnprHealthBot profiles only) Specify the TCP port number on the BNG where HealthBot communicates with the BNG to collect telemetry data.

Default: 50051

system (IP PoolBot)

Syntax

Hierarchy Level

Description

Configure attributes that determine how IP PoolBot behaves for alarms and transactions.

Options

alarm-hold-time seconds(Optional) Specify how long IP PoolBot waits before it checks again on a given alarm for further mitigation.

Default: 90

Range: 5 through 900

transaction-time-out seconds(Optional) Specify how long IP PoolBot waits for a transaction to complete before it declares that the transaction has stalled (timed out). A transaction consists of a list of tasks. For example, an apportion transaction consists of a task to get an address, a task to provision the entity, and a task to update run-time state. If any task in a transaction fails, the previously executed tasks in the list are rolled back. For example, if the provisioning task fails, then the task to get the address is rolled back, and the address is returned to the partition.

Default: 240

Range: 60 through 900