Use the juniper.device.system Ansible Module to Halt, Reboot, or Shut
Down Junos Devices
Use the juniper.device.system Ansible module to halt, reboot, or
shut down devices running Junos OS or devices running Junos OS Evolved.
Use Ansible to Halt, Reboot, or Shut Down Devices
Juniper Networks provides an Ansible module that you can use to halt, reboot, or shut down devices running Junos OS or devices running Junos OS Evolved. Table 1 outlines the available module.
|
Collection |
Module Set |
Module Name |
|---|---|---|
|
|
You can use the juniper.device.system
module to request the following operations on Junos devices. By default, the
module immediately executes the requested operation and performs the operation
on all Routing Engines in a dual Routing Engine or Virtual Chassis setup.
-
An immediate system halt, reboot, or shutdown
-
A halt, reboot, or shutdown operation with an optional delay
-
A halt, reboot, or shutdown operation scheduled at a specific date and time
The system module requires one argument,
action, which defines the action to perform. Table 2 defines the action parameter values and gives a brief
description of each action as well as the corresponding CLI command. For
information about the "zeroize" action, see Use the juniper.device.system Ansible Module to Restore a Junos Device to its Factory-Default State.
|
|
Description |
Equivalent CLI Command |
|---|---|---|
|
|
Gracefully shut down the Junos OS software or the Junos OS Evolved software but maintain system power |
|
|
|
Reboot the Junos OS software or the Junos OS Evolved software |
|
|
|
Gracefully shut down the Junos OS software or the Junos OS Evolved software and power off the Routing Engines |
|
The following Ansible playbook uses the juniper.device.system
module with action: reboot to immediately reboot all Routing
Engines on the hosts in the specified inventory group.
---
- name: Reboot Junos devices
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Reboot all REs on the device
juniper.device.system:
action: reboot
How to Perform a Halt, Reboot, or Shut Down with a Delay or at a Specified Time
You can delay the halt, reboot, or shutdown operation by a specified number of
minutes. To add a delay, set the optional in_min parameter to
the number of minutes that the system should wait before executing the
operation. The following task requests a reboot of all Routing Engines in 30
minutes:
---
- name: Reboot Junos devices
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Reboot all REs in 30 minutes
juniper.device.system:
action: reboot
in_min: 30
You can also schedule the halt, reboot, or shutdown operation at a specific time.
To schedule a time, include the at parameter, which takes a
string that can be specified in one of the following ways:
-
now—Immediately initiate the halt, reboot, or shut down of the software. -
+minutes—Number of minutes from now when the requested action is initiated. -
yymmddhhmm—Absolute time at which to initiate the requested action, specified as year, month, day, hour, and minute. -
hh:mm—Absolute time on the current day at which to initiate the requested action, specified in 24-hour time.
The following task schedules a system shutdown of all Routing Engines at 22:30 on the current day:
tasks:
- name: Shut down all REs at 22:30 on the current day
juniper.device.system:
action: shutdown
at: "22:30"
How to Specify the Target Routing Engine
By default, the juniper.device.system module performs the
requested operation on all Routing Engines in a dual Routing Engine or Virtual
Chassis setup. You can also instruct the module to perform the operation on only
the Routing Engine to which the application is connected or to perform the
operation on all Routing Engines except the one to which the application is
connected.
To specify the Routing Engines, you use the all_re and
other_re parameters. Table 3 summarizes the all_re and other_re values
that are required to execute the requested operation on specific Routing
Engines.
|
Affected Routing Engines |
|
|
|---|---|---|
|
All Routing Engines (default) |
Omit or set to |
– |
|
Only the connected Routing Engine |
Set to |
– |
|
All Routing Engines except the Routing Engine to which the application is connected |
– |
Set to |
To explicitly indicate that the operation should be performed on all Routing
Engines in a dual Routing Engine or Virtual Chassis setup, include the
all_re: true argument, which is the default.
---
- name: Reboot Junos devices
hosts: dc1
connection: local
gather_facts: no
tasks:
- name: Reboot all Routing Engines
juniper.device.system:
action: reboot
all_re: true
To perform the requested action on only the Routing Engine to which the
application is connected, include the all_re: false
argument.
tasks:
- name: Reboot only the connected Routing Engine
juniper.device.system:
action: reboot
all_re: false
To perform the requested action on all Routing Engines in the system except for
the Routing Engine to which the application is connected, include the
other_re: true argument.
tasks:
- name: Shut down all other Routing Engines
juniper.device.system:
action: shutdown
other_re: true
How to Reboot or Shut Down a VM Host
On devices that have Routing Engines with VM host support, Junos OS runs as a
virtual machine (VM) over a Linux-based host (VM host). The
juniper.device.system module supports the
vmhost argument, which enables you to reboot or shut down a
VM Host.
When you include the action: reboot and
vmhost: true arguments, the system reboots the host OS and
compatible Junos OS on all Routing Engines by executing the
<request-vmhost-reboot> RPC, which corresponds to the
request vmhost reboot operational mode command.
Similarly, when you include the action: shutdown and
vmhost: true arguments, the system shuts down the host OS
and compatible Junos OS on all Routing Engines by executing the
<request-vmhost-poweroff> RPC, which corresponds to
the request vmhost power-off operational mode command.
The following playbook performs a VM host reboot, which reboots both the host OS and the guest Junos OS.
---
- name: Reboot VM Hosts
hosts: vm_hosts
connection: local
gather_facts: no
tasks:
- name: Reboot VM host
juniper.device.system:
action: reboot
vmhost: true
all_re: false
Example: Use Ansible to Reboot Junos Devices
The juniper.device.system module enables you to halt, reboot, or
shut down a Junos device. This example uses the system module to
reboot a Junos device.
Requirements
This example uses the following hardware and software components:
-
Configuration management server running Ansible 2.17 or later with the
juniper.devicecollection installed -
Junos device with NETCONF enabled and a user account configured with appropriate permissions
-
SSH public/private key pair configured for the appropriate user on the Ansible control node and Junos device
-
Existing Ansible inventory file with required hosts defined
Overview
This example presents an Ansible playbook that uses the
juniper.device.system module to reboot a Junos device. The
value of the module’s action argument defines the operation to
execute on the host.
When calling the module from a playbook, we recommend that you use an interactive
prompt to confirm that the user does intend to reboot the specified devices. If
a user unintentionally runs the playbook and there is no check, it could
adversely affect any networks that require the impacted devices. As a
precaution, this playbook uses an interactive prompt to verify that the user
intends to reboot the devices. The prompt requires that the user manually type
'yes' on the command line to execute the module. If
the Confirmation check task fails, the Ansible control node
skips the other tasks in the play for that device.
This playbook includes the Check NETCONF connectivity task,
which utilizes the ansible.builtin.wait_for module to try to
establish a NETCONF session with the Junos device using the default NETCONF port
830. If the control node fails to establish a NETCONF session with the device
during playbook execution, then it skips the remaining tasks in the play for
that device.
The reboot task executes the juniper.device.system module
provided that the confirmation and NETCONF checks were successful. The
action argument is set to reboot, which
indicates that the software should be rebooted. The in_min: 2
argument instructs the module to wait for the specified number of minutes before
executing the reboot command. This provides time for any users to log out of the
system.
The task stores the module result in the result variable and
notifies two handlers. The pause_for_reboot handler waits a
specified amount of time after the reboot operation is initiated to prevent the
wait_reboot handler from falsely detecting that the device
is online before the reboot takes place. The wait_reboot
handler then tries to establish a session with the device to verify that the
device comes back online after the reboot. The
wait_time_after_reboot variable defines the length of time
that the control node attempts to reconnect with the device.
Configuration
Create and Execute the Ansible Playbook
Step-by-Step Procedure
To create a playbook that uses the juniper.device.system
module to reboot a Junos device:
Include the boilerplate for the playbook and this play, which executes the modules locally.
--- - name: Reboot Junos devices hosts: dc1 connection: local gather_facts: no
Define or import any necessary variables.
vars: wait_time_after_reboot: 300 netconf_port: 830Create an interactive prompt to prevent users from accidentally executing the module without first understanding the implications.
vars_prompt: - name: "reboot_confirmation" prompt: "This playbook reboots devices. Enter 'yes' to continue" private: noCreate the task that confirms the user’s intent.
tasks: - name: Confirmation check fail: msg="Playbook run confirmation failed" when: reboot_confirmation != "yes"(Optional) Create a task to verify NETCONF connectivity.
- name: Check NETCONF connectivity ansible.builtin.wait_for: host: "{{ inventory_hostname }}" port: "{{ netconf_port }}" timeout: 5Create the task to reboot the device after a specified number of minutes and then notify the handlers.
- name: Reboot all Routing Engines on the Junos device juniper.device.system: action: reboot in_min: 2 all_re: true register: result notify: - pause_for_reboot - wait_reboot(Optional) Create a task to print the response.
- name: Print response ansible.builtin.debug: var: resultCreate the handler that pauses after rebooting and the handler that verifies that the device comes back online after rebooting.
The handler names should be the same as those referenced in the reboot task.
handlers: - name: pause_for_reboot pause: seconds: 180 when: result.reboot - name: wait_reboot ansible.builtin.wait_for: host: "{{ inventory_hostname }}" port: "{{ netconf_port }}" timeout: "{{ wait_time_after_reboot }}" when: result.reboot
Results
On the Ansible control node, review the completed playbook. If the playbook does not display the intended code, repeat the instructions in this example to correct the playbook.
---
- name: Reboot Junos devices
hosts: dc1
connection: local
gather_facts: no
vars:
wait_time_after_reboot: 300
netconf_port: 830
vars_prompt:
- name: "reboot_confirmation"
prompt: "This playbook reboots devices. Enter 'yes' to continue"
private: no
tasks:
- name: Confirmation check
fail: msg="Playbook run confirmation failed"
when: reboot_confirmation != "yes"
- name: Check NETCONF connectivity
ansible.builtin.wait_for:
host: "{{ inventory_hostname }}"
port: "{{ netconf_port }}"
timeout: 5
- name: Reboot all Routing Engines on the Junos device
juniper.device.system:
action: reboot
in_min: 2
all_re: true
register: result
notify:
- pause_for_reboot
- wait_reboot
- name: Print response
ansible.builtin.debug:
var: result
handlers:
- name: pause_for_reboot
pause:
seconds: 180
when: result.reboot
- name: wait_reboot
ansible.builtin.wait_for:
host: "{{ inventory_hostname }}"
port: "{{ netconf_port }}"
timeout: "{{ wait_time_after_reboot }}"
when: result.reboot
Execute the Playbook
Procedure
Step-by-Step Procedure
To execute the playbook:
-
Issue the
ansible-playbookcommand on the control node, and provide the playbook path and any desired options.user@ansible-cn:~/ansible$ ansible-playbook ansible-pb-junos-reboot.yaml This playbook reboots devices. Enter 'yes' to continue: yes PLAY [Reboot Junos devices] ************************************************** TASK [Confirmation check] **************************************************** skipping: [dc1a.example.net] TASK [Check NETCONF connectivity] ******************************************** ok: [dc1a.example.net] TASK [Reboot all Routing Engines on the Junos device] ************* changed: [dc1a.example.net] TASK [Print response] ******************************************************** ok: [dc1a.example.net] => { "result": { "action": "reboot", "all_re": true, "changed": true, "failed": false, "media": false, "msg": "reboot successfully initiated. Response got Shutdown at Fri Dec 11 17:36:50 2020. [pid 11595]", "other_re": false, "reboot": true, "vmhost": false } } RUNNING HANDLER [pause_for_reboot] ******************************************* Pausing for 180 seconds (ctrl+C then 'C' = continue early, ctrl+C then 'A' = abort) ok: [dc1a.example.net] RUNNING HANDLER [wait_reboot] ************************************************ ok: [dc1a.example.net] PLAY RECAP ******************************************************************* dc1a.example.net : ok=5 changed=1 unreachable=0 failed=0 skipped=1 rescued=0 ignored=0
Verification
Verify the Reboot
Purpose
Verify that the Junos device successfully rebooted.
Action
When you execute the playbook, review the output of the
wait_reboot task for each device.
RUNNING HANDLER [wait_reboot] ************************************************* ok: [dc1a.example.net]
Meaning
The wait_reboot result indicates whether the control
node successfully established a session with the device after it
rebooted. If the result indicates success, the device is online.
Change History Table
Feature support is determined by the platform and release you are using. Use Feature Explorer to determine if a feature is supported on your platform.
juniper.device collection Release
1.0.3, the system module supports shutting down a VM
Host.