code.grnet.gr Git - archipelago/blob - docs/archipelago_deploy.rst

   1 Archipelago management
   2 ======================
   3
   4 This section describes basic Archipelago management and configuration.
   5
   6 Archipelago installation
   7 ************************
   8
   9 Archipelago consists of the following packages:
  10
  11 * ``libxseg0``: libxseg used to communicate over shared memory segments
  12 * ``python-xseg``: python bindings for libxseg
  13 * ``archipelago-kernel-dkms``: contains archipelago kernel modules to provide
  14   block devices to be used as vm disks
  15 * ``archipleago-modules-source``: contains archipelago kernel modules source, to
  16   build deb packages with the help of module assistant
  17 * ``python-archipelago``: archipelago python module. Includes archipelago and
  18   vlmc functionality.
  19 * ``archipelago``: user space tools and peers for the archipelago management and
  20   volume composition
  21 * ``archipelago-rados``: user space storage driver to enable RADOS support
  22 * ``archipelago-ganeti``: ganeti ext storage scripts, that enable ganeti to
  23   provision VMs over archipelago
  24
  25
  26
  27 Installing ``archipelago-ganeti`` from the apt repository should fetch all the
  28 necessary dependencies, based on the dkms infrastructure. Install also
  29 ``archipelago-rados`` to enable RADOS storage backend.
  30
  31
  32 .. code-block:: console
  33
  34     $ apt-get install archipelago-ganeti archipelago-rados
  35
  36 .. tip:: Archipelago does not start automatically after installation. Please
  37          review the configuration file, make any appropriate changes to the
  38          default configuration (e.g. default max segment size) and start it
  39          manually.
  40
  41 If a dkms based install is not desired, build your own archipelago-modules
  42 package by installing archipelago-modules-source and performing:
  43
  44 .. code-block:: console
  45
  46     $ m-a build --text-mode --kvers-list "target kernel to build" archipelago-modules
  47
  48 .. note:: Kernel modules need linux-kernel >= 3.2
  49
  50 .. warning:: Archipelago currently supports only x86_64 architecture.
  51
  52 Archipelago configuration
  53 *************************
  54
  55 Archipelago configuration file is located to :
  56 ``/etc/archipelago/archipelago.conf``
  57
  58
  59 ``SEGMENT_PORTS``
  60     **Description** : Max number of ports in the segment.
  61
  62 ``SEGMENT_SIZE``
  63     **Description** : Shared memory size, used for IPC.
  64
  65 ``XSEGBD_START``
  66     **Description** : Start port of xsegbd peers
  67
  68 ``XSEGBD_END``
  69     **Description** : End port of xsegbd peers
  70
  71 ``VTOOL_START``
  72     **Description** : Start port of vlmc tool.
  73
  74 ``VTOOL_END``
  75     **Description** : End port of vlmc tool.
  76
  77 ``roles``
  78     **Description** : A list of (role_name, role_type) tuples, which is used to
  79     deploy the archipelago user space peers. Order matters.
  80
  81 ``role_name { 'setting': value }``
  82     **Description** : A python dictionary which holds the parameters of they
  83     userspace peers.
  84
  85 Common peer options:
  86  * ``portno_start``: Start port of the peer.
  87  * ``portno_end``: End port of the peer.
  88  * ``log_level``: Loggging lever for the peer. Available logging levers 0-3.
  89  * ``nr_ops``: Number of ops, each peer can have flying.
  90
  91 .. * ``logfile``:
  92 .. * ``pidfile``:
  93
  94 Filed specific options:
  95  * ``nr_threads``: Number of I/O threads to server requests.
  96  * ``archip_dir``: Directory where the files will reside.
  97  * ``fdcache``: Number of file descriptors to be kept open.
  98
  99 Rados specific options:
 100  * ``nr_threads``: Number of threads to server requests.
 101  * ``pool``: RADOS pool where the objects will be stored.
 102
 103 Mapper specified options:
 104  * ``blockerb_port``: Port for communication with the blocker responsible for
 105    the data blocks.
 106  * ``blockerm_port``: Port for communication with the blocker responsible for
 107    the maps.
 108
 109 Vlmc specific options:
 110  * ``blocker_port``: Port for communication with the blocker responsible for the
 111    data blocks.
 112  * ``mapper_port``: Port for communication with the mapper.
 113
 114 Archipelago commands
 115 ********************
 116
 117 ``archipelago`` provides basic functionality for archipelago.
 118
 119 Usage:
 120
 121 .. code-block:: console
 122
 123   $ archipelago [-u] command
 124
 125
 126 Currently it supports the following commands:
 127
 128 * ``start [role]``
 129   Starts archipelago or the specified peer.
 130 * ``stop [role]``
 131   Stops archipelago or the specified peer.
 132 * ``restart [role]``
 133   Restarts archipelago or the specified peer.
 134 * ``status``
 135   Show the status of archipelago.
 136
 137 ``role`` is one of the roles defined on the configuration file.
 138
 139
 140 ``start``, ``stop``, ``restart`` can be combined with the ``-u / --user`` option
 141 to affect only the userspace peers supporting archipelago.
 142
 143 Archipelago advanced commands
 144 *****************************
 145
 146 The ``vlmc`` tool provides a way to interact with archipelago volumes
 147
 148 Usage:
 149
 150 .. code-block:: console
 151
 152   $ vlmc command [args]
 153
 154 Available commands:
 155
 156 * **map**: maps the volume to a xsegbd device
 157
 158   Usage: ``$ vlmc map <volumename>``
 159
 160 * **unmap**: unmaps the specified device from the system.
 161
 162   Usage: ``vlmc unmap </dev/xsegbd[1-..]>``
 163
 164 * **create**: creates a new volume with an optional specified size from an optional
 165   specified snapshot
 166
 167   Usage: ``vlmc create <volumename> --snap <snapname> --size <size>``
 168
 169   Usage: ``vlmc create <volumename> --snap <snapname>``
 170
 171   Usage: ``vlmc create <volumename> --size <size>``
 172
 173   The ``--snap`` and ``--size`` are both optional, but at least one of them is
 174   mandatory. If snap is not specified, then a blank volume with the specified
 175   size is created. If size is not specified, the new volume inherits the size
 176   from the snapshot.
 177
 178 * **remove**: removes the volume.
 179
 180   Usage: ``vlmc remove <volumename>``
 181
 182   This does not actually delete the blocks, just make the volume inaccessible
 183   for usage. The actual blocks are removed later, when a garbage collection is
 184   invoked.
 185
 186 * **list**: Provides a list of archipelago volume currently found on storage
 187
 188   Usage: ``vlmc list``
 189
 190 * **info**: shows volume information. Currently returns only the volume size.
 191
 192   Usage: ``vlmc info <volumename>``
 193
 194 * **open**: opens an archipelago volume. That is, taking all the necessary locks
 195   and also make the rest of the infrastructure aware of the operation.
 196
 197   Usage: ``vlmc open <volumename>``
 198
 199   This operation succeeds if the volume is alread opened by the current host.
 200
 201 * **close**: closes an archipelago volume. That is, performing all the necessary
 202   functions in the insfrastrure to successfully release the volume. Also
 203   releases all the acquired locks.
 204
 205   Usage: ``vlmc close <volumename>``
 206
 207   A explicit ``close`` command should be invoked an explicit ``open``, to
 208   release the volume, unless another action triggered an implicit ``close``.
 209
 210 * **lock**: locks a volume. This step allow the administrator to lock an
 211   archipelago volume, independently from the rest of the infrastructure.
 212
 213   Usage: ``vlmc lock <volumename>``
 214
 215   The locks are idempotent for the current owner of the lock. That is, a lock
 216   operation will succeed when the volume is already locked by the same blocker.
 217
 218 * **unlock**: unlocks a volume. This allow the administrator to unlock a volume,
 219   independently from the rest of the infrastructure.
 220
 221   Usage: ``vlmc unlock [-f] <volumename>``
 222
 223   The unlock option can be performed only by the blocker that acquired the lock
 224   in the first place. To unlock a volume from another blocker, ``-f`` option
 225   must be used to break the lock.
 226
 227 Archipelago volume locking system
 228 *********************************
 229
 230 Archipelago uses volume storage based locks, to get exclusive access to volumes.
 231 Since a volume can be active in only one VM, locks are used to ensure that
 232 restriction. But since locks are storage based, they are permanent and
 233 independent from the process or subsystem that acquired them. So, if a process,
 234 an archipelago deployment on a node misbehaves or crashes, or even a hypervisor
 235 management software (e.g. ganeti) fails to perform a migration, there might be an
 236 inconsistency. Knowledge of locking behavior in archipelago is necessary in
 237 order to surpass these problems.
 238
 239 #TODO FILL ME
 240
 241 locking is cached on mapper
 242
 243 Persistent locks. held if a process/blocker stops/fails/crashes
 244
 245 lock is acquired with best effort mode:
 246
 247 * reads: try to get it, but do not fail if not able to. just don't cache anything
 248 * writes: try to get it, and wait until the owner free it.
 249 * snapshot/remove/create etc: Try to get it. Fail if not able to.
 250
 251 during migrations: blah blah