How to: Enable the Debug utility on instance API via Mac or Linux¶

When the BIG-IP Next Central Manager, which normally manages the instance, is unavailable, follow this procedure to enable the Debug utility by making direct request to the BIG-IP Next instance API.

Recommendation: Use the BIG-IP Next Central manager to enable the Debug utility. For directions on how to enable the Debug utility using BIG-IP Next Central Manager see: How to: Log in and use the Debug utility

Overview¶

Enable Debug utility Mac and Linux Connect to the Debug utility from client workstation Disable the Debug utility

Prerequisites¶

Curl HTTP client installed on workstation with network access to the Instance management IP address
Workstation
- Curl HTTP Client installed
- Network access to the management IP of Instance
- SSH client
Management credentials currently set for the instance. These are set when the BIG-IP instance is added to the BIG-IP Next Central Manager.

Enable Debug utility Mac and Linux¶

Request authentication token from instance API¶

The procedure below is an example of how to request an authentication token and saving the token as a variable.

Set the variables for requesting an authentication token:
1. Set the username that will be used to authenticate to the BIG-IP Next instance, the default is admin-cm. This username was created when the BIG-IP was discovered by the BIG-IP Next Central Manager
```
export username=<admin-cm>
```
2. Set the password corresponding to the username:
```
password=<password>
```
3. Set the IP address for the BIG-IP Next instance:
```
 instance_ip=<IP_address_BIGIP>
```
Make an API request for an authentication token to connect directly to the BIG-IP Next instance. Be sure to include the instance port number(5443) within the API URL. This command will request an authentication token, then utilize the jq command to filter the token from the response and store the auth token in a variable.
```
token=$(curl -sk -u "${username}:${password}" https://${instance_ip}:5443/api/v1/login | jq -r '.token')
```
Note: Repeat the above request as many time as necessary to get new auth tokens after they expire.
Check that the variable named token is populated: Note: This is optional, to view the token and add it directly to the API request to connect to the instance.

echo $token

Note: The token expires after five minutes.

Having requested the token and populated a variable (or copied it), it is now possible to send API requests to the BIG-IP Next instance.

Make Request to enable instance Debug utility (Mac and Linux)¶

To enable the Debug utility make an HTTP PUT request to the BIG-IP instance API. The body of the PUT request will contain the details, in JSON format, that will allow a client to connect to the Debug shell using the SSH public key of the client workstation to authenticate.

Note: A username should be created using a combination of uppercase letters (A-Z), lowercase letters (a-z), and numbers (0-9) to enable the debug utility. Although the following are allowed, avoid using them as they will impact enabling the debug utility:

underscores (_), dashes (-) or dots (.).
starting the username with an uppercase letter or number.

Populate variables that will be used to create a PUT data file¶

Save the client public SSH key to variable.

Example

export client_public_ssh_key=$(cat ~/.ssh/id_rsa.pub)

Set a variable for the port number the SSH client will use to connect to the Debug utility.

export port_number=<port_number>

Important: Substitute <port_number> with the chosen port number for connecting to the Debug utility. Any number not currently in use will suffice.

Example

export port_number=4422

Create a file that contains the following and name it put_template.

{
    "sshPublicKey": "${client_public_ssh_key}",
    "allowedIps": [
        "0.0.0.0/0"
    ],
    "username": "${username}",
    "port": ${port_number}
}

Note: Users with usernames that do not follow the pattern ‘^[a-z][a-z0-9]’ — specifically those starting with an uppercase letter, number, or containing underscores (_), dashes (-), or dots (.)—will need to enable the utility via OpenAPI.

Create a data file based off the template and populated variables using the envsubst command.

Example

envsubst < put_template > put.json

Note: There is no output from the above command. To see resulting file contents use: cat put.json.

Confirm that the put.json file contains the values substituted for the variables, and that the JSON is formatted correctly, use the jq command. If there is a problem with the JSON formatting jq will give an error. If the JSON is correct jq will output the file contents formatted.

cat put.json | jq .

Example output

% cat put.json | jq .
{
  "sshPublicKey": "ssh-rsa AAAAB3NzaC1yc2EAAAADAQABAAABgQDmkeRGhRHHZjdIes1GMWbFhW8gDkpUn7fDpPtqRisw7yrzCEoa84eUbK/GilKvSMqlU2plcW8/ANlOn1vHvVR3ULerZksRU+LYVAH7hBSJA6M9hN+u2wz6wW+UfdJkcIXFnTBBQzg1F3HAd5vZR+l5lsv0YniUO0vtiPqfDAe61ksimHOnIwoKfjKhhnA1n3fYLE7vSOIR+1fuQnUsi0wrBD46kDtFVnSevhLrT9DXJVloO8KPf8hL+CXQ5+u2sID0nZlFJZ/j8ztYBYnYTnCHmtlmjMd0KBv78huaO5LqdCyXTp+SKrg4SVFMYwDnz9a0qquKzMvQ97zJWYPDBVfPyMdRDtzYy+EjClYs382ZNOmGr6dDHyEpRt/QnNxXXT9rkFJHkvZ2UlDegs40mDVwL5vYRH2MpCJp+jGxlTzRv5jcq9framwY+bpx1WRD9X6bMs/gliiku6b1pjYe7QPzkK/iTUEFXvo2zJr7g6VYrzdSgHTtAKQPThSahzBjr0= t.thomas@client.local",
  "allowedIps": [
    "0.0.0.0/0"
  ],
  "username": "admin",
  "port": 4422
}

Save the instance system ID to a variable. The ID will be used in the request to enable the Debug utility.

Example

system_id=$(curl -sk -H "Authorization: Bearer ${token}" https://${instance_ip}:5443/api/v1/systems | jq -r '._embedded.systems[].id')

Make request to enable Debug utility¶

Make a PUT request to the instance API using the data file and the populated variables.

Example

curl -sk -H "Authorization: Bearer ${token}" -H "Content-Type: application/json" https://${instance_ip}:5443/api/v1/actions/systems/${system_id}/dataplane-debug/enable -X PUT --upload-file put.json

Connect to the Debug utility from client workstation¶

ssh <username>@<BIG-IP Instance IP> -p <port_number>

Example

ssh admin@10.154.73.131 -p 4422

Example output Debug utility command line

 % ssh admin@10.154.73.131 -p 4422

****************************************
*                                      *
* Welcome to BIG-IP Next Debug Console *
*                                      *
****************************************
Last login: Tue Oct 10 19:34:28 2023 from 100.76.0.78
/

See: Debug utility tools for more information on the tools available in the Debug utility.

Disable the Debug utility¶

Once troubleshooting is completed, the Debug utility should be disabled.

Example

curl -sk -H "Authorization: Bearer ${token}" -H "Content-Type: application/json" https://${instance_ip}:5443/api/v1/actions/systems/${system_id}/dataplane-debug/disable -X PUT

Note: If the authentication token expires request a new auth token and try the request again.

token=$(curl -sk -u "${username}:${password}" https://${instance_ip}:5443/api/v1/login | jq -r '.token')

The last request will turn off the Debug utility and will need to be enabled again before it can be accessed.