.. _guide-customer-networks-import: Importing customer networks data into Argus with argus-cli ========================================================== This guide will quickly go through the steps required to create and update Argus customer networks from CSV data. It assumes ``argus-cli`` is already installed and :ref:`configured `. The ``argus-cli`` command used for importing customer network data is :ref:`argus-cli customer-networks update`. Preparing data for the import ----------------------------- The :ref:`customer-networks update` command expects CSV data with some constraints : - Only :ref:`fields recognized by the command ` should be present - If a CSV header is present, it must only use such fields With than in mind, we can prepare data for the import. As an example, we can use the following CSV data : .. code-block:: text 10.10.1.0/24,first network 10.10.1.0/24,second network This contains the bare minimum : the network address and its description. The rest of this section will go through the different fields that can be added to the data - note that the order of fields in the CSV does not matter and can be specified when running the import command. network addresses ^^^^^^^^^^^^^^^^^ As shown above, network addresses can be provided using decimal notation, optionally providing the netmask using slash notation. Example without netmask : .. code-block:: text 10.10.1.0,first network 10.10.1.0,second network .. warning:: If the netmask is not provided, it will default to ``/32``. Example with netmask : .. code-block:: text 10.10.1.0/24,first network 10.10.1.0/24,second network subnet masks ^^^^^^^^^^^^ Subnet masks can be specified as part of the network address, as shown in the example above. However, it is also possible to provide them in a separate column. In that case, the full mask must be provided. As an example, the example data above can also be provided as : .. code-block:: text 10.10.1.0,255.255.255.0,first network 10.10.1.0,255.255.255.0,second network zones ^^^^^ A network can be assigned one of 4 zones : - ``UNKNOWN`` - ``INTERNAL`` - ``EXTERNAL`` - ``DMZ`` If an unexpected value is found in the CSV data, it will be set to the default : ``UNKNOWN``. Example : .. code-block:: text 10.10.1.0/24,first network,INTERNAL 10.10.1.0/24,second network,INTERNAL locations ^^^^^^^^^ The location indicates the physical location of a given network. In order for a network to be attached to a given location, that location must exist in Argus and be accessible to the user running the import. The list of available locations can be obtained with the :ref:`customer-networks list ` command : .. code-block:: bash argus-cli customer-networks list-locations Where ```` is the customer's shortName. .. note:: There is a set of "global" shared locations that can always be used, but they will only be listed if the API key used to run that command has the `viewGlobalLocations` function enabled. If a location can not be resolved, it will be set to the default : ``unknown``. Running the import ------------------ Once the data data is ready, it can be imported into Argus using the :ref:`customer-networks update` command. The synopsys of the command is : .. code-block:: text argus-cli customer-networks update CUSTOMER FILE where ``CUSTOMER`` is the customer's Argus short name and ``FILE`` the path to the CSV file with the data. Specifying the input format ^^^^^^^^^^^^^^^^^^^^^^^^^^^ As mentioned above, the order of fields does not matter and can be specified. There are two ways of specigying the format : using the ``--format`` option, or using CSV headers. .. warning:: Only :ref:`valid fields` should be present in the data. Unexpected fields will cause unexpected behavior. .. note:: If the CSV data uses another delimiter than ``,``, it can be specified using the :option:`argus-cli customer-networks update --delimiter` option. Using the ``--format`` option """"""""""""""""""""""""""""" The :option:`argus-cli customer-networks update --format` option takes a comma-separated list of fields expected to be present in the input CSV data. The valid fields names are ``address`` (or ``Network``), ``description``, ``subnet_mask``, ``zone`` and location (or ``LocationShortName``). They are case-sensitive. The default format is ``address,description``, so the following data can be imported without any specification : .. code-block:: text 10.10.1.0/24,first network 10.10.1.0/24,second network As an example, the following data can be imported with ``--format description,address,netmask,zone,location`` : .. code-block:: text first network,10.10.1.0,255.255.255.0,INTERNAL,oslo second network,10.10.1.0,255.255.255.0,INTERNAL,oslo Using CSV headers """"""""""""""""" Alternatively, if the first row of the CSV data is a header, this header can be used by the import command by using the :option:`argus-cli customer-networks update --first-line-defines-format` option. Example : .. code-block:: text description,address,netmask,zone,location first network,10.10.1.0,255.255.255.0,INTERNAL,oslo second network,10.10.1.0,255.255.255.0,INTERNAL,oslo Updating and deleting networks ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, the :ref:`customer-networks update` command will only create new networks in argus : - existing networks will not be updated, even if the CSV data differs frpm Argus data - no existing networks will be deleted This behavior can be changed using the :option:`argus-cli customer-networks update --replace` and :option:`argus-cli customer-networks update --delete-missing` flags : - if :option:`argus-cli customer-networks update --replace` is set, existing networks will be deleted and re-created with values from the input CSV data if values are different than those set in Argus - if :option:`argus-cli customer-networks update --delete-missing` is set, networks that are present in Argus but not in the input CSV data will be deleted in Argus. .. warning:: As an import using these flags can be destructive, it is recommended to perform a dry run (:option:`argus-cli customer-networks update --dry`) to ensure the the outcome of the import will be as expected. running the import non-interactively ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ By default, the :ref:`customer-networks update` will prompt for confirmation before creating or deleting Argus data. In order to run the command non-interactively, set the :option:`argus-cli customer-networks update --always-yes` flag. .. warning:: Use with caution if combined with the :option:`argus-cli customer-networks update --replace` and/or :option:`argus-cli customer-networks update --delete-missing` flags.