1.. _junos_platform_options:
2
3***************************************
4Junos OS Platform Options
5***************************************
6
7The `Juniper Junos OS <https://galaxy.ansible.com/junipernetworks/junos>`_ supports multiple connections. This page offers details on how each connection works in Ansible and how to use it.
8
9.. contents::
10  :local:
11
12Connections available
13================================================================================
14
15.. table::
16    :class: documentation-table
17
18    ====================  ==========================================  =========================
19    ..                    CLI                                         NETCONF
20
21                          ``junos_netconf`` & ``junos_command``       all modules except ``junos_netconf``,
22                          modules only                                which enables NETCONF
23    ====================  ==========================================  =========================
24    Protocol              SSH                                         XML over SSH
25
26    Credentials           uses SSH keys / SSH-agent if present        uses SSH keys / SSH-agent if present
27
28                          accepts ``-u myuser -k`` if using password  accepts ``-u myuser -k`` if using password
29
30    Indirect Access       via a bastion (jump host)                   via a bastion (jump host)
31
32    Connection Settings   ``ansible_connection:                       ``ansible_connection:
33                          ``ansible.netcommon.network_cli``           ``ansible.netcommon.netconf``
34
35    |enable_mode|         not supported by Junos OS                   not supported by Junos OS
36
37    Returned Data Format  ``stdout[0].``                              * json: ``result[0]['software-information'][0]['host-name'][0]['data'] foo lo0``
38                                                                      * text: ``result[1].interface-information[0].physical-interface[0].name[0].data foo lo0``
39                                                                      * xml: ``result[1].rpc-reply.interface-information[0].physical-interface[0].name[0].data foo lo0``
40    ====================  ==========================================  =========================
41
42.. |enable_mode| replace:: Enable Mode |br| (Privilege Escalation)
43
44
45The ``ansible_connection: local`` has been deprecated. Please use ``ansible_connection: ansible.netcommon.network_cli`` or ``ansible_connection: ansible.netcommon.netconf`` instead.
46
47Using CLI in Ansible
48====================
49
50Example CLI inventory ``[junos:vars]``
51--------------------------------------
52
53.. code-block:: yaml
54
55   [junos:vars]
56   ansible_connection=ansible.netcommon.network_cli
57   ansible_network_os=junipernetworks.junos.junos
58   ansible_user=myuser
59   ansible_password=!vault...
60   ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
61
62
63- If you are using SSH keys (including an ssh-agent) you can remove the ``ansible_password`` configuration.
64- If you are accessing your host directly (not through a bastion/jump host) you can remove the ``ansible_ssh_common_args`` configuration.
65- If you are accessing your host through a bastion/jump host, you cannot include your SSH password in the ``ProxyCommand`` directive. To prevent secrets from leaking out (for example in ``ps`` output), SSH does not support providing passwords via environment variables.
66
67Example CLI task
68----------------
69
70.. code-block:: yaml
71
72   - name: Retrieve Junos OS version
73     junipernetworks.junos.junos_command:
74       commands: show version
75     when: ansible_network_os == 'junipernetworks.junos.junos'
76
77
78Using NETCONF in Ansible
79========================
80
81Enabling NETCONF
82----------------
83
84Before you can use NETCONF to connect to a switch, you must:
85
86- install the ``ncclient`` python package on your control node(s) with ``pip install ncclient``
87- enable NETCONF on the Junos OS device(s)
88
89To enable NETCONF on a new switch via Ansible, use the ``junipernetworks.junos.junos_netconf`` module through the CLI connection. Set up your platform-level variables just like in the CLI example above, then run a playbook task like this:
90
91.. code-block:: yaml
92
93   - name: Enable NETCONF
94     connection: ansible.netcommon.network_cli
95     junipernetworks.junos.junos_netconf:
96     when: ansible_network_os == 'junipernetworks.junos.junos'
97
98Once NETCONF is enabled, change your variables to use the NETCONF connection.
99
100Example NETCONF inventory ``[junos:vars]``
101------------------------------------------
102
103.. code-block:: yaml
104
105   [junos:vars]
106   ansible_connection=ansible.netcommon.netconf
107   ansible_network_os=junipernetworks.junos.junos
108   ansible_user=myuser
109   ansible_password=!vault |
110   ansible_ssh_common_args='-o ProxyCommand="ssh -W %h:%p -q bastion01"'
111
112
113Example NETCONF task
114--------------------
115
116.. code-block:: yaml
117
118   - name: Backup current switch config (junos)
119     junipernetworks.junos.junos_config:
120       backup: yes
121     register: backup_junos_location
122     when: ansible_network_os == 'junipernetworks.junos.junos'
123
124
125.. include:: shared_snippets/SSH_warning.txt
126
127.. seealso::
128
129       :ref:`timeout_options`
130