1.. _ansible.netcommon.net_ping_module: 2 3 4************************** 5ansible.netcommon.net_ping 6************************** 7 8**Tests reachability using ping from a network device** 9 10 11Version added: 1.0.0 12 13.. contents:: 14 :local: 15 :depth: 1 16 17 18Synopsis 19-------- 20- Tests reachability using ping from network device to a remote destination. 21 22 23 24 25Parameters 26---------- 27 28.. raw:: html 29 30 <table border=0 cellpadding=0 class="documentation-table"> 31 <tr> 32 <th colspan="1">Parameter</th> 33 <th>Choices/<font color="blue">Defaults</font></th> 34 <th width="100%">Comments</th> 35 </tr> 36 <tr> 37 <td colspan="1"> 38 <div class="ansibleOptionAnchor" id="parameter-"></div> 39 <b>count</b> 40 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 41 <div style="font-size: small"> 42 <span style="color: purple">-</span> 43 </div> 44 </td> 45 <td> 46 <b>Default:</b><br/><div style="color: blue">5</div> 47 </td> 48 <td> 49 <div>Number of packets to send.</div> 50 </td> 51 </tr> 52 <tr> 53 <td colspan="1"> 54 <div class="ansibleOptionAnchor" id="parameter-"></div> 55 <b>dest</b> 56 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 57 <div style="font-size: small"> 58 <span style="color: purple">-</span> 59 / <span style="color: red">required</span> 60 </div> 61 </td> 62 <td> 63 </td> 64 <td> 65 <div>The IP Address or hostname (resolvable by switch) of the remote node.</div> 66 </td> 67 </tr> 68 <tr> 69 <td colspan="1"> 70 <div class="ansibleOptionAnchor" id="parameter-"></div> 71 <b>source</b> 72 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 73 <div style="font-size: small"> 74 <span style="color: purple">-</span> 75 </div> 76 </td> 77 <td> 78 </td> 79 <td> 80 <div>The source IP Address.</div> 81 </td> 82 </tr> 83 <tr> 84 <td colspan="1"> 85 <div class="ansibleOptionAnchor" id="parameter-"></div> 86 <b>state</b> 87 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 88 <div style="font-size: small"> 89 <span style="color: purple">-</span> 90 </div> 91 </td> 92 <td> 93 <ul style="margin: 0; padding: 0"><b>Choices:</b> 94 <li>absent</li> 95 <li><div style="color: blue"><b>present</b> ←</div></li> 96 </ul> 97 </td> 98 <td> 99 <div>Determines if the expected result is success or fail.</div> 100 </td> 101 </tr> 102 <tr> 103 <td colspan="1"> 104 <div class="ansibleOptionAnchor" id="parameter-"></div> 105 <b>vrf</b> 106 <a class="ansibleOptionLink" href="#parameter-" title="Permalink to this option"></a> 107 <div style="font-size: small"> 108 <span style="color: purple">-</span> 109 </div> 110 </td> 111 <td> 112 <b>Default:</b><br/><div style="color: blue">"default"</div> 113 </td> 114 <td> 115 <div>The VRF to use for forwarding.</div> 116 </td> 117 </tr> 118 </table> 119 <br/> 120 121 122Notes 123----- 124 125.. note:: 126 - For targets running Python, use the :ref:`ansible.builtin.shell <ansible.builtin.shell_module>` module along with ping command instead. 127 - This module is supported on ``ansible_network_os`` network platforms. See the :ref:`Network Platform Options <platform_options>` for details. 128 129 130 131Examples 132-------- 133 134.. code-block:: yaml 135 136 - name: Test reachability to 10.10.10.10 using default vrf 137 ansible.netcommon.net_ping: 138 dest: 10.10.10.10 139 140 - name: Test reachability to 10.20.20.20 using prod vrf 141 ansible.netcommon.net_ping: 142 dest: 10.20.20.20 143 vrf: prod 144 145 - name: Test unreachability to 10.30.30.30 using default vrf 146 ansible.netcommon.net_ping: 147 dest: 10.30.30.30 148 state: absent 149 150 - name: Test reachability to 10.40.40.40 using prod vrf and setting count and source 151 ansible.netcommon.net_ping: 152 dest: 10.40.40.40 153 source: loopback0 154 vrf: prod 155 count: 20 156 157 - Note: 158 - For targets running Python, use the M(ansible.builtin.shell) module along with ping command instead. 159 - Example: 160 name: ping 161 shell: ping -c 1 <remote-ip> 162 163 164 165Return Values 166------------- 167Common return values are documented `here <https://docs.ansible.com/ansible/latest/reference_appendices/common_return_values.html#common-return-values>`_, the following are the fields unique to this module: 168 169.. raw:: html 170 171 <table border=0 cellpadding=0 class="documentation-table"> 172 <tr> 173 <th colspan="1">Key</th> 174 <th>Returned</th> 175 <th width="100%">Description</th> 176 </tr> 177 <tr> 178 <td colspan="1"> 179 <div class="ansibleOptionAnchor" id="return-"></div> 180 <b>commands</b> 181 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 182 <div style="font-size: small"> 183 <span style="color: purple">list</span> 184 </div> 185 </td> 186 <td>always</td> 187 <td> 188 <div>Show the command sent.</div> 189 <br/> 190 <div style="font-size: smaller"><b>Sample:</b></div> 191 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">['ping vrf prod 10.40.40.40 count 20 source loopback0']</div> 192 </td> 193 </tr> 194 <tr> 195 <td colspan="1"> 196 <div class="ansibleOptionAnchor" id="return-"></div> 197 <b>packet_loss</b> 198 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 199 <div style="font-size: small"> 200 <span style="color: purple">string</span> 201 </div> 202 </td> 203 <td>always</td> 204 <td> 205 <div>Percentage of packets lost.</div> 206 <br/> 207 <div style="font-size: smaller"><b>Sample:</b></div> 208 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">0%</div> 209 </td> 210 </tr> 211 <tr> 212 <td colspan="1"> 213 <div class="ansibleOptionAnchor" id="return-"></div> 214 <b>packets_rx</b> 215 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 216 <div style="font-size: small"> 217 <span style="color: purple">integer</span> 218 </div> 219 </td> 220 <td>always</td> 221 <td> 222 <div>Packets successfully received.</div> 223 <br/> 224 <div style="font-size: smaller"><b>Sample:</b></div> 225 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">20</div> 226 </td> 227 </tr> 228 <tr> 229 <td colspan="1"> 230 <div class="ansibleOptionAnchor" id="return-"></div> 231 <b>packets_tx</b> 232 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 233 <div style="font-size: small"> 234 <span style="color: purple">integer</span> 235 </div> 236 </td> 237 <td>always</td> 238 <td> 239 <div>Packets successfully transmitted.</div> 240 <br/> 241 <div style="font-size: smaller"><b>Sample:</b></div> 242 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">20</div> 243 </td> 244 </tr> 245 <tr> 246 <td colspan="1"> 247 <div class="ansibleOptionAnchor" id="return-"></div> 248 <b>rtt</b> 249 <a class="ansibleOptionLink" href="#return-" title="Permalink to this return value"></a> 250 <div style="font-size: small"> 251 <span style="color: purple">dictionary</span> 252 </div> 253 </td> 254 <td>always</td> 255 <td> 256 <div>Show RTT stats.</div> 257 <br/> 258 <div style="font-size: smaller"><b>Sample:</b></div> 259 <div style="font-size: smaller; color: blue; word-wrap: break-word; word-break: break-all;">{'avg': 2, 'max': 8, 'min': 1}</div> 260 </td> 261 </tr> 262 </table> 263 <br/><br/> 264 265 266Status 267------ 268 269 270Authors 271~~~~~~~ 272 273- Jacob McGill (@jmcgill298) 274