docs/user-guide/daexim-user-guide.rst

   1 .. _daexim-user-guide:
   2
   3 Data Export/Import User Guide
   4 =============================
   5
   6
   7 Overview
   8 --------
   9
  10 Data Export/Import is known as "daexim" (pronounced 'deck-sim') for
  11 short. The intended audience are administrators responsible for
  12 operations of OpenDaylight.
  13
  14 Data Export/Import provides an API (via RPCs) to request the bulk
  15 transfer of OpenDaylight system data between its internal data stores
  16 and the local file system. This can be used for scheduling data exports,
  17 checking the status of data being exported, canceling data export jobs,
  18 importing data from files in the file systems, and checking the import
  19 status.
  20
  21 Such export and import of data can be used during system upgrade,
  22 enabling the development of administrative procedures that make
  23 reconfigurations of the base system without concern of internal data
  24 loss.
  25
  26 Data Export produces a models declaration file and one or more data
  27 files. The models declaration file records exactly which YANG models
  28 were loaded (by module name, revision date and namespace). The data
  29 file(s) contain data store data as per the draft-ietf-netmod-yang-json
  30 RFC.
  31
  32 Data Import takes a models declaration file and zero or more data
  33 files. The models declaration file is used to check that the listed
  34 models are loaded before importing any data. Data is imported into each
  35 data store in turn with one transaction executed for each data store,
  36 irrespective of the number of files for that data store, as inter-module
  37 data dependencies may exist. Existing data store data may be cleared
  38 before importing.
  39
  40
  41 Data Export Import Architecture
  42 -------------------------------
  43
  44 The daexim feature is a single feature. This feature leverages the
  45 existing infrastructure provided by MD-SAL and yangtools.
  46
  47
  48 Installing the Feature
  49 ----------------------
  50
  51 To install the feature perform the following steps.
  52
  53 .. code:: bash
  54
  55     karaf > feature:install odl-daexim-all
  56
  57
  58 The interactions with this feature are via Restconf RPCs. The details
  59 are provided in the `Tutorials`.
  60
  61
  62 Tutorials
  63 ---------
  64
  65 The following tutorials provide examples of REST API that are supported
  66 by the Data Export/Import feature.  As for all ODL RESTCONF calls, the
  67 following are the common setting for REST calls:
  68
  69 * **Headers:**
  70
  71   * **Content-Type:** ``application/json``
  72
  73   * **Accept:** ``application/json``
  74
  75   * **Authentication:** ``admin:admin``
  76
  77 * **Method:** ``HTTP POST``
  78 * <controller-ip>: Host (or IP) where OpenDaylight controller is
  79   running, e.g. localhost
  80 * <restconf-port>: TCP port where RESTCONF has been configured to
  81   listen, e.g. 8181 by default
  82
  83 The files created by export are placed in a subdirectory called
  84 ``daexim/`` in the installation directory of OpenDaylight. Similarly files
  85 to import must be placed in this ``daexim/`` subdirectory.
  86
  87
  88
  89 Scheduling Export
  90 ^^^^^^^^^^^^^^^^^
  91
  92 The **schedule-export** RPC exports the data at a specific time in the
  93 future. The ``run-at`` time may be specified as an absolute UTC time or a
  94 relative offset from the server clock. Attempts to schedule an export in
  95 the past times are rejected. Each file has a JSON-encoded object that
  96 contains module data from the corresponding data store. Module data is
  97 not included in the object for any module identified in the exclusion
  98 list. Each file contains at least one empty JSON object. In a clustered
  99 environment, if *local-node-only* is provided with a value of *true*,
 100 the export operation is performed only on the node on which the RPC was
 101 received; otherwise, the export operation is performed on all nodes in
 102 the cluster.
 103
 104 **URL:** ``http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:schedule-export``
 105
 106 **Payload:**
 107
 108 .. code:: json
 109
 110   {
 111      "input": {
 112        "data-export-import:run-at": 500
 113      }
 114   }
 115
 116
 117
 118 Checking Export Status
 119 ^^^^^^^^^^^^^^^^^^^^^^
 120
 121 The **status-export** RPC checks the status of the exported data. If the
 122 status has the value of ``initial``, an export has not been scheduled. If
 123 the status has the value of ``scheduled``, ``run-at`` indicates the time at
 124 which the next export runs. If the status has the value of
 125 ``in-progress``, ``run-at`` indicates the time at which the running export
 126 was scheduled to start. A status of ``tasks`` indicates activities that
 127 are scheduled and currently being performed. The ``tasks`` status serves
 128 as an indicator of progress and success of the activity. If the status
 129 has any other value, ``run-at`` indicates the time at which the last
 130 export was scheduled to start; and ``tasks`` indicates the activities that
 131 were undertaken. If the status for any node has failed, the
 132 corresponding reason for failure is listed.
 133
 134 **URL:** ``http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:status-export``
 135
 136 **Payload:** No payload
 137
 138
 139
 140 Canceling Scheduled Export
 141 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 142
 143 The **cancel-export** RPC cancels an already scheduled data export
 144 job. To cancel the export, the server stops the tasks that are running
 145 (where possible, immediately), clears any scheduled export time value,
 146 and releases the associated resources. This RPC may be called at any
 147 time, whether an export is in progress, scheduled or not yet
 148 scheduled. The returned result is ``True`` when the server has
 149 successfully cleared tasks, the state, and resources. The status is
 150 ``False`` on failure to do so. Note that if no export is scheduled or
 151 running, there is no tasks for the server to clear. Therefore, the
 152 return result is ``True`` because the server cannot fail.
 153
 154 **URL:** ``http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:cancel-export``
 155
 156 **Payload:** No payload
 157
 158
 159 Importing from a file
 160 ^^^^^^^^^^^^^^^^^^^^^
 161
 162 The **immediate-import** RPC imports data from files already present in
 163 the file system.
 164
 165 **URL:** ``http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:immediate-import``
 166
 167 **Payload:**
 168
 169 .. code:: json
 170
 171   {
 172      "input" : {
 173        "check-models" : true,
 174        "clear-stores" : "all"
 175      }
 176   }
 177
 178
 179
 180
 181 Status of Import
 182 ^^^^^^^^^^^^^^^^
 183
 184 The **status-import** RPC checks the last import status. If the status
 185 has the value of ``initial``, an import has not taken place. For all other
 186 values of status, ``imported-at`` indicates the time at which the
 187 restoration has taken place. List nodes hold status about the
 188 restoration for each node.
 189
 190 **URL:** ``http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:status-import``
 191
 192 **Payload:** No payload
 193
 194
 195 Importing from a file automatically on boot
 196 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 197
 198 Any files placed inside the ``daexim/boot`` subdirectory are automatically
 199 imported on start-up.  The import performed is the exact same as the one by
 200 explicit **immediate-import** RPC, which imports from files ``daexim/``, except
 201 it happens automatically.
 202
 203 The import on boot happens after all other ODL OSGi bundles have successfully
 204 started.  The INFO log and **status import** automatically reflect when the boot
 205 import is planned (via ``boot-import-scheduled``), when the boot import is
 206 ongoing (via ``boot-import-in-progress``), and when the boot import fails
 207 (via ``boot-import-failed``).
 208
 209 Upon completion or failure of this boot import, the files inside the
 210 ``daexim/boot`` directory are renamed to ``.imported`` in order to avoid
 211 another import on the next start.