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

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