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 The 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   * Content-Type: application/json
  71   * Accept: application/json
  72   * Authentication: admin:admin
  73 * Method: HTTP POST
  74 * <controller-ip> : Host (or IP) where OpenDaylight controller is
  75   running, e.g. localhost
  76 * <restconf-port> : TCP port where RESTCONF has been configured to
  77   listen, e.g. 8181 by default
  78
  79 The files created by export are placed in a subdirectory called
  80 *daexim/* in the installation directory of OpenDaylight. Similarly files
  81 to import must be placed in this *daexim/* subdirectory.
  82
  83
  84
  85 Scheduling Export
  86 ^^^^^^^^^^^^^^^^^
  87
  88 The **schedule-export** RPC exports the data at a specific time in the
  89 future. The *run-at* time may be specified as an absolute UTC time or a
  90 relative offset from the server clock. Attempts to schedule an export in
  91 the past times are rejected. Each file has a JSON-encoded object that
  92 contains module data from the corresponding data store.  Module data is
  93 not included in the object for any module identified in the exclusion
  94 list. Each file contains at least one empty JSON object.
  95
  96 URL:
  97   http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:schedule-export
  98
  99 Payload:
 100
 101 .. code:: json
 102
 103   {
 104      "input": {
 105        "data-export-import:run-at": 500
 106      }
 107   }
 108
 109
 110
 111 Checking Export Status
 112 ^^^^^^^^^^^^^^^^^^^^^^
 113
 114 The **status-export** RPC checks the status of the exported data. If the
 115 status has the value of *initial*, an export has not been scheduled. If
 116 the status has the value of *scheduled*, *run-at* indicates the time at
 117 which the next export runs. If the status has the value of
 118 *in-progress*, *run-at* indicates the time at which the running export
 119 was scheduled to start. A status of *tasks* indicates activities that
 120 are scheduled and currently being performed. The *tasks* status serves
 121 as an indicator of progress and success of the activity. If the status
 122 has any other value, *run-at* indicates the time at which the last
 123 export was scheduled to start; and *tasks* indicates the activities that
 124 were undertaken. If the status for any node has failed, the
 125 corresponding reason for failure is listed.
 126
 127 URL:
 128   http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:status-export
 129
 130 Payload:
 131   No payload
 132
 133
 134
 135 Canceling Scheduled Export
 136 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 137
 138 The **cancel-export** RPC cancels an already scheduled data export
 139 job. To cancel the export, the server stops the tasks that are running
 140 (where possible, immediately), clears any scheduled export time value,
 141 and releases the associated resources. This RPC may be called at any
 142 time, whether an export is in progress, scheduled or not yet
 143 scheduled. The returned result is *True* when the server has
 144 successfully cleared tasks, the state, and resources. The status is
 145 *False* on failure to do so. Note that if no export is scheduled or
 146 running, there is no tasks for the server to clear. Therefore, the
 147 return result is *True* because the server cannot fail.
 148
 149 URL:
 150   http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:cancel-export
 151
 152 Payload:
 153   No payload
 154
 155
 156 Import from a file
 157 ^^^^^^^^^^^^^^^^^^
 158
 159 The **immediate-import** RPC imports data from files already present in
 160 the file system.
 161
 162 URL:
 163   http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:immediate-import
 164
 165 Payload:
 166
 167 .. code:: json
 168
 169   {
 170      "input" : {
 171        "check-models" : true,
 172        "clear-stores" : "all"
 173      }
 174   }
 175
 176
 177
 178
 179 Status of Import
 180 ^^^^^^^^^^^^^^^^
 181
 182 The **status-import** RPC checks the last import status. If the status
 183 has the value of *initial*, an import has not taken place. For all other
 184 values of status, *imported-at* indicates the time at which the
 185 restoration has taken place. List nodes hold status about the
 186 restoration for each node.
 187
 188 URL:
 189   http://<controller-ip>:<restconf-port>/restconf/operations/data-export-import:status-import
 190
 191 Payload:
 192   No payload