{
 "cells": [
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "# How to handle connections to devices\n",
    "\n",
    "## Automatically\n",
    "\n",
    "By default, connections are handled automatically:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 1,
   "metadata": {},
   "outputs": [],
   "source": [
    "from nornir import InitNornir\n",
    "from nornir_napalm.plugins.tasks import napalm_get\n",
    "\n",
    "import pprint"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 2,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "{'facts': {'fqdn': 'localhost',\n",
      "           'hostname': 'localhost',\n",
      "           'interface_list': ['Ethernet1',\n",
      "                              'Ethernet2',\n",
      "                              'Ethernet3',\n",
      "                              'Ethernet4',\n",
      "                              'Management1'],\n",
      "           'model': 'vEOS',\n",
      "           'os_version': '4.15.5M-3054042.4155M',\n",
      "           'serial_number': '',\n",
      "           'uptime': '...',\n",
      "           'vendor': 'Arista'}}\n"
     ]
    }
   ],
   "source": [
    "nr = InitNornir(config_file=\"handling_connections/config.yaml\")\n",
    "rtr = nr.filter(name=\"rtr00\")\n",
    "r = rtr.run(\n",
    "    task=napalm_get,\n",
    "    getters=[\"facts\"]\n",
    ")\n",
    "pprint.pprint(r[\"rtr00\"][0].result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Manually\n",
    "\n",
    "In some circumstances, you may want to manage connections manually. To do so you can use \n",
    "[open_connection](../api/nornir/core/inventory.html#nornir.core.inventory.Host.open_connection), [close_connection](../api/nornir/core/inventory.html#nornir.core.inventory.Host.close_connection), [close_connections](../api/nornir/core/inventory.html#nornir.core.inventory.Host.close_connections) and [Nornir.close_connections](../api/nornir/core/__init__.html#nornir.core.__init__.Nornir.close_connections). For instance:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 3,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "Connection succeeded: True\n",
      "{'facts': {'fqdn': 'localhost',\n",
      "           'hostname': 'localhost',\n",
      "           'interface_list': ['Ethernet1',\n",
      "                              'Ethernet2',\n",
      "                              'Ethernet3',\n",
      "                              'Ethernet4',\n",
      "                              'Management1'],\n",
      "           'model': 'vEOS',\n",
      "           'os_version': '4.15.5M-3054042.4155M',\n",
      "           'serial_number': '',\n",
      "           'uptime': '...',\n",
      "           'vendor': 'Arista'}}\n"
     ]
    }
   ],
   "source": [
    "def task_manages_connection_manually(task):\n",
    "    task.host.open_connection(\"napalm\", configuration=task.nornir.config)\n",
    "    r = task.run(\n",
    "        task=napalm_get,\n",
    "        getters=[\"facts\"]\n",
    "    )\n",
    "    task.host.close_connection(\"napalm\")\n",
    "    \n",
    "nr = InitNornir(config_file=\"handling_connections/config.yaml\")\n",
    "rtr = nr.filter(name=\"rtr00\")\n",
    "r = rtr.run(\n",
    "    task=task_manages_connection_manually,\n",
    ")\n",
    "\n",
    "# this time the result in position 0 is the connection\n",
    "print(f\"Connection succeeded: {not r['rtr00'][0].failed}\")\n",
    "# and the result in position 1 is the result for napalm_get\n",
    "pprint.pprint(r[\"rtr00\"][1].result)"
   ]
  },
  {
   "cell_type": "markdown",
   "metadata": {},
   "source": [
    "## Specifying connection parameters\n",
    "\n",
    "When using the [open_connection](../api/nornir/core/inventory.html#nornir.core.inventory.Host.open_connection) you can specify any parameters you want. If you don't, or if you let nornir open the connection automatically, nornir will read those parameters from the inventory. You can specify standard attributes at the object level if you want to reuse them across different connections or you can override them for each connection. For example:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": 4,
   "metadata": {},
   "outputs": [
    {
     "name": "stdout",
     "output_type": "stream",
     "text": [
      "dev1.group_1:\r\n",
      "    port: 65020\r\n",
      "    hostname: localhost\r\n",
      "    username:\r\n",
      "    password: a_password\r\n",
      "    platform: eos\r\n",
      "    data:\r\n",
      "        some_string_to_test_any_all: prefix\r\n",
      "        my_var: comes_from_dev1.group_1\r\n",
      "        www_server: nginx\r\n",
      "        role: www\r\n",
      "        nested_data:\r\n",
      "            a_dict:\r\n",
      "                a: 1\r\n",
      "                b: 2\r\n",
      "            a_list: [1, 2]\r\n",
      "            a_string: asdasd\r\n",
      "    groups:\r\n",
      "        - group_1\r\n",
      "    connection_options:\r\n",
      "        paramiko:\r\n",
      "            port: 65020\r\n",
      "            hostname:\r\n",
      "            username: root\r\n",
      "            password: docker\r\n",
      "            platform: linux\r\n",
      "            extras: {}\r\n",
      "        dummy:\r\n",
      "            hostname: dummy_from_host\r\n",
      "            port:\r\n",
      "            username:\r\n",
      "            password:\r\n",
      "            platform:\r\n",
      "            extras:\r\n",
      "                blah: from_host\r\n"
     ]
    }
   ],
   "source": [
    "!sed '2,36!d' ../../tests/inventory_data/hosts.yaml"
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Python 3",
   "language": "python",
   "name": "python3"
  },
  "language_info": {
   "codemirror_mode": {
    "name": "ipython",
    "version": 3
   },
   "file_extension": ".py",
   "mimetype": "text/x-python",
   "name": "python",
   "nbconvert_exporter": "python",
   "pygments_lexer": "ipython3",
   "version": "3.9.7"
  }
 },
 "nbformat": 4,
 "nbformat_minor": 2
}