Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
ON THIS PAGE
 

How to Use the APM Utility and CLI Commands

Access APM Utility Commands

SUMMARY After you've installed the Address Pool Manager (APM) application, you can perform the following administration functions.

You can use the APM utility script (apm) to administer the application and to access the CLI that you use to configure the address management functions. The Juniper APM installation places the utility script in /var/local/apm and creates a symbolic link to the script in /usr/local/bin/apm.

You can use the apm utility script (which uses the Kubernetes kubectl utility commands) to do the following:

  • Create and delete objects.
  • Provide log access.
  • Conduct interactive sessions with pod containers.
  • Display the status of the APM objects.

Using the apm utility script simplifies many of your administrative duties. The script performs the tasks you need to manage APM, while masking the complexity of the kubectl command.

Table 1 lists the commands that you can invoke with the apm utility script and describes the action that occurs. Many of the individual commands have options that you can specify.

Table 1: APM Utility Script Commands

Name

Action

cli

Access the CLI that you can use to configure APM features and to monitor the current status for managed BNGs.

db

Connect to the APM database CLI.

restart

Restart one or more specified services. To run this command, you need sudo root privileges.

Note:

Introduced in Release 3.1.0.

logs

Display APM logs.
svc-logs Display APM persistent logs.
Note:

Introduced in Release 3.1.0

objects

Display the Kubernetes objects authored by APM that are necessary for orchestrating the APM pods.

setup

Set up the APM application as part of the installation process. To run this command, you need sudo root privileges.

start

Start a specific APM service or all APM services.

status

Display the current status of the APM services.

stop

Stop all APM services.

service

 Connect to a running APM service.

uninstall

Remove the APM application from the local system. To run this command, you need sudo root privileges.

version

Display the version number of the installed APM application.

upgrade

 Upgrade an APM service. To run this command, you need sudo root privileges.
Note:

Introduced in Release 3.1.0

Use the following general syntax to issue a command:

  • For a short option:

  • For a long option:

To display a list of available commands with a brief description, use either the h or help option:

To display the options for a specific command:

Start or Stop APM Services

Use the apm utility script to start or stop all APM services. The services start in order of dependency. Essential services (db and cmgd) start first, followed by the other services. The services stop in reverse order of dependency.

  • To start all APM services:

    Note:

    We recommend that you use the apm start ––services option to start individual services or a set of services only for troubleshooting under the guidance of a Juniper Networks support representative.
    Note:

    By default, APM starts from factory defaults. The configuration is reset to its initial state, any persistent state database (DB) is cleared, and any persistent logs are cleared. In APM Release 3.1.0, after the initial setup, you can use apm start –-retain to retain its previous state.

  • To stop all APM services:

Check the Status of APM Services

Use the apm status utility script to check the status of each APM service (functional component) listed in Table 2. The status shows whether a service is running, has exited, or has not started. It also displays the service name on the Kubernetes pod. You can compare uptime for the services to quickly see whether any service has been restarted.

Table 2: Services Displayed with the status Command

Service

Service Name on the Pod

addr-man—Address manager

jnpr-apm-addrman

cfg-man—Configuration manager

jnpr-apm-cfgman

cmgd—CLI management

jnpr-apm-cmgd

db—Redis (Remote Dictionary Server), which provides the persistent database structure.

jnpr-apm-redis

dbHaMon—Redis sentinel that monitors and detects failures in the primary instance and elects a worker instance to serve as the new primary instance.

jnpr-apm-redis-sentinels

ent-man—Entity manager

jnpr-apm-entman

prov-man—Provisioning manager

jnpr-apm-provman

apm-fluentd—A set of pods that collect microservice

 jnpr-apm-fluentd
log-man—Use this helper pod to collate, filter, and display logs that have been archived in persistent files. jnpr-apm-logman
Note:

Introduced in Release 3.1.0

To check the status:

  1. Display the service status.
  2. (Optional) Render the version information in JavaScript Object Notation (JSON) format, which is useful for scripting interfaces.

For example:

Display Kubernetes Objects

Use the apm objects utility script to display the Kubernetes objects that are necessary for the orchestration of the APM pods. For example:

Display Logging

SUMMARY Use the apm logs utility script to display the logs of events that occur while APM is running. Use the apm svc-logs utility script to display file-based logs collected and stored since the time APM is started. You enable file-based logging when you set up APM.

Display APM Logging

Use the apm logs utility script to display the logs of events that occur while APM is running. The event logs include events such as those shown in the following non-exhaustive list:

  • Pool-domain registration events

  • Address allocation failures

  • Network entity connection failures

  • Startup messages

  • Network entity resynchronization events

  • Pool and partition utilization threshold and depletion warnings

By default, APM sends logs to the standard output (stdout) of the service. The output displays the circular buffer of all services or of a specified service. You can also enable logging to follow the log output of the running services. Following the log output creates an open session that continuously streams the logs to stdout.

The APM logging functions mask the underlying complexities of the kubectl log command that is collecting the log information. You can still use the kubectl log command, but that is outside the scope of this documentation.

Note:

You can use third-party applications to capture and redirect the stdout stream for the container. Refer to your third-party documentation for assistance. You can also configure Docker with different logging drivers to redirect stdout. Refer to your Docker documentation for assistance.

To display APM logs for all services:

Best Practice:

Use the apm logs ––services option only when you are troubleshooting under the guidance of a Juniper Networks support representative.

To follow the logs for all services, specify the follow option (-f):

To view logs from previous instances of the containers in a Kubernetes pod, specify the previous container option (-p):

You can use standard Ubuntu conventions to redirect the logs to a file or to the terminal and to a file. Refer to the Ubuntu documentation for more information, but you can use the following examples as a starting point:

  • Redirect all logs to only a file.

  • Redirect all logs to both the screen and to a file.

By default, the utility command reports logs of all severity levels. You can limit the number of logs that are reported by setting a severity level when you start APM services. Include the --log-level option when you start services to specify the minimum severity level of logs that are reported when you also use the logs command. Logs are reported for the specified level and all levels that are more severe. The default level is debug, which is the lowest severity level. This means that by default logs are reported for all levels.

When you set a severity level, it applies to all services.

  • To set the severity level for all services:

Best Practice:

Use the ––services option only for troubleshooting under the guidance of a Juniper Networks support representative.

You can specify any of the following severity levels, in order of increasing severity:

Table 3: Severity Level
Severity Level Description
debug Detailed information that is typically of interest only when you are trying to diagnose a problem. These logs are often very frequent.
info Events or non-error conditions of interest. Logs at this level provide confirmation that everything is working as expected. These logs are generally not very frequent.
warning Indicates that something unexpected happened or that some problem might occur in the near future. A simple example of the latter is the disk space low warning that indicates that you might run out of disk space soon. In either case, the software is still working as expected, but you might want to monitor it more closely. These logs are generally not very frequent.
error Indicates that a more serious problem has prevented the software from performing some function, but the software has handled the problem as gracefully as possible to continue functioning.
critical A serious error that indicates that the program itself might be unable to continue running.

You can use the --logset option to display logs either for only APM services or for only prebuilt services. If you do not use this option, then only the APM services logs are displayed.

To display logs for only APM services:

To display logs for prebuilt services:

Prebuilt services are services borrowed from other sources to provide infrastructure functions for APM. These sources include cMGD, haproxy, redis, and redis-sentinel. For example, redis provides database and messaging services, cMGD provides a configuration/CLI service, and so on.

Display APM SVC Logging

Use the apm svc-logs utility script (in APM Release 3.1.0) to display file-based log output. You can enable file-based logging when you start APM. If you select file-based logging during APM setup, APM displays logs from the file regardless of the running state of APM. Collected logs are rotated such that the capacity limit of the persistent volume is not exceeded. If you don't select file-based logging during setup, the apm-svc-logs utility displays the message File-based logging is not enabled.

To display SVC logs:

By default, the utility command reports service logs of all types.

To select logs for a specific service, use the –- services option:

The –-services argument specifies the set of APM microservices to filter on. You can specify any of the following services:

  • cfg-man
  • prov-man
  • ent-man
  • addr-man

To limit the number of logs displayed, you can specify the filter to limit the start of the output:

Where:

  • --since SINCE—The --since option specifies the timestamp in the YYYY-mm-dd-hh:mm:ss format to begin displaying log entries at or after the provided timestamp value till the end of the log is reached.

  • --tail—Display log entries from the end of the log (default is 100 entries).

  • --head —Display log entries from the beginning of the log (default is 100 entries).

To specify the number of entries to override the number of default entries displayed:

To specify the no-color option to disable colored-text output (used to distinguish logs from different microservices):

Determine the APM Version

Use the apm version utility script to determine the version number of the installed APM release.

To display the release version:

To display the version information for APM and for each service:

Use the -j option to render the version information in JavaScript Object Notation (JSON) format.

Uninstall and Remove APM

Use the apm utility script to uninstall the APM configuration. The uninstall command reverts the actions you performed when setting up APM. Use this command to return APM to the state it was in immediately after you installed the application but before you did any setup configuration.

To uninstall APM:

After you uninstall APM, we recommend that you use the Debian uninstall procedure to remove the entire package.

How to Access APM Configuration and Operational Commands

Access the APM CLI

To access the CLI prompt, enter the following apm utility script command:

Enter a question mark to see the available top-level CLI commands. This list of commands is a subset of the Junos OS top-level commands.

For an overview of Junos OS CLI basics, see Day One: Exploring the Junos CLI. For more detailed information, see the CLI User Guide.

Access and Use CLI Configuration Statements

  1. Use the APM utility command apm cli to access the top-level CLI prompt.
  2. Access configuration mode to configure APM and the information that APM uses to configure a managed router.
  3. Enter CLI statements to configure the APM-managed BNGs, pool domains, pools, and system attributes.
  4. Save and activate the configuration. This command succeeds only when there are no configuration syntax errors.
  5. (Optional) Exit configuration mode and return to the top-level CLI prompt.

Access and Use CLI Operational Commands

To monitor APM, view APM configuration and statistics, or run certain operations manually:

  1. Use the APM utility command apm cli to access the top-level CLI prompt.
  2. Enter specific commands.

    • Use show commands to display statistics and the relationships between partitions, BNGs, pool domains, and pools.

    • Use request commands to manually initiate certain APM operations.