code.grnet.gr Git - kamaki/blob - docs/commands.rst

   1 List of commands
   2 ================
   3
   4 Kamaki commands follow this scheme::
   5
   6     [kamaki] <object> <action> [identifiers] [non-positional arguments]
   7
   8 In this context, objects are not services, but virtual objects like a server, a
   9 file or an image. The action concerns objects of the specified type. Some
  10 actions (e.g. "delete" or "info") need to operate on an existing object. The
  11 identifiers strictly identify this object and they can have the form of an id
  12 (e.g., `server delete <SERVER_ID>`) or a foreign key (e.g.,
  13 `port create <NETWORK_ID> <DEVICE_ID>`)
  14
  15 The examples bellow showcase some commands. The kamaki-shell (check
  16 `Usage section <usage.html#interactive-shell>`_ for details) is chosen as the
  17 execution environment.
  18
  19
  20 user (Identity/Astakos)
  21 -----------------------
  22
  23 .. code-block:: text
  24
  25     info          Get info for (current) session user
  26     uuid2name     Get user name(s) from uuid(s)
  27     authenticate  Authenticate a user and get all authentication information
  28     list          List (cached) session users
  29     add           Authenticate user by token and add to kamaki session (cache)
  30     name2uuid     Get user uuid(s) from name(s)
  31     select        Select user from the (cached) list as current session user
  32     delete        Delete user (token) from the (cached) list of session users
  33
  34 Showcase: get user information
  35 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  36
  37 In the following, cloud URL and TOKEN were set in a previous step (see
  38 `setup section <setup.html>`_ or the
  39 `quick setup guide <usage.html#quick-setup>`_)
  40
  41 .. code-block:: console
  42     :emphasize-lines: 1,4
  43
  44     * Enter user context *
  45     [kamaki]: user
  46
  47     * Authenticate user *
  48     [user]: info
  49     ...
  50     name:  My Real Name
  51     id:  ab1cde23-45fg-6h7i-8j9k-10l1m11no2pq
  52
  53     [user]: exit
  54     [kamaki]:
  55
  56 project (Astakos)
  57 -----------------
  58
  59 .. code-block:: text
  60
  61     info          Get details for a project
  62     unsuspend     Resume a suspended project (special privileges needed)
  63     suspend       Suspend a project (special privileges needed)
  64     list          List all projects
  65     create        Apply for a new project
  66     modify        Modify a project
  67     terminate     Terminate a project (special privileges needed)
  68     application   Application management commands
  69     membership    Project membership management commands
  70     reinstate     Reinstate a terminated project (special privileges needed)
  71
  72 quota (Account/Astakos)
  73 -----------------------
  74
  75 .. code-block:: text
  76
  77     list          Get user quotas
  78     info          Get quota for a service (cyclades, pithos, astakos)
  79
  80 resource (Astakos)
  81 ------------------
  82
  83 .. code-block:: text
  84
  85     list          List user resources
  86
  87 flavor (Compute/Cyclades)
  88 -------------------------
  89
  90 .. code-block:: text
  91
  92     info:  Get flavor details
  93     list:  List flavors
  94
  95 Showcase: show details for flavor with id 43
  96 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  97
  98 .. code-block:: console
  99     :emphasize-lines: 1,4
 100
 101     * Enter flavor context *
 102     [kamaki]: flavor
 103
 104     * Get details about flavor with id 43 *
 105     [flavor]: info 43
 106     SNF:disk_template:  drbd
 107     cpu:  4
 108     disk:  10
 109     id:  43
 110     name:  C4R2048D10
 111     ram:  2048
 112
 113 image (Image/Plankton)
 114 ----------------------
 115
 116 .. code-block:: text
 117
 118     info          Get image metadata
 119     list          List images accessible by user
 120     register      (Re)Register an image file to an Image service
 121     modify        Add / update metadata and properties for an image
 122     unregister    Unregister an image (does not delete the image file)
 123
 124 Showcase: Pick an image and list the properties
 125 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 126
 127 .. code-block:: console
 128     :emphasize-lines: 1,4,18
 129
 130     * Enter image context *
 131     [kamaki]: image
 132
 133     * list all available images *
 134     [image]: list
 135     926ab1c5-2d85-49d4-aebe-0fce712789b9 Windows Server 2008
 136      container_format:  bare
 137      disk_format:  diskdump
 138      id:  926ab1c5-2d85-49d4-aebe-0fce712789b9
 139      size:  11917066240
 140      status:  available
 141     78262ee7-949e-4d70-af3a-85360c3de57a Windows Server 2012
 142      container_format:  bare
 143      disk_format:  diskdump
 144      id:  78262ee7-949e-4d70-af3a-85360c3de57a
 145      size:  11697913856
 146      status:  available
 147     5ed5a29b-292c-4fe0-b32c-2e2b65628635 ubuntu
 148      container_format:  bare
 149      disk_format:  diskdump
 150      id:  5ed5a29b-292c-4fe0-b32c-2e2b65628635
 151      size:  2578100224
 152      status:  available
 153     1f8454f0-8e3e-4b6c-ab8e-5236b728dffe Debian_Wheezy_Base
 154      container_format:  bare
 155      disk_format:  diskdump
 156      id:  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
 157      size:  795107328
 158      status:  available
 159
 160     * Get details for image with id 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe *
 161     [image]: info 1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
 162      name: Debian_Wheezy_Base
 163      container_format:  bare
 164      disk_format:  diskdump
 165      id:  1f8454f0-8e3e-4b6c-ab8e-5236b728dffe
 166      size:  795107328
 167      status:  available
 168      owner:  s0m3-u53r-1d (user@example.com)
 169         DESCRIPTION:  Debian Wheezy Base (Stable)
 170         GUI:  No GUI
 171         KERNEL:  2.6.32
 172         OS:  debian
 173         OSFAMILY:  linux
 174         ROOT_PARTITION:  1
 175         SORTORDER:  1
 176         USERS:  root
 177
 178 imagecompute (Compute/Cyclades)
 179 -------------------------------
 180
 181 .. code-block:: text
 182
 183     info      Get detailed information on an image
 184     list      List images
 185     modify    Modify image properties (metadata)
 186     delete    Delete an image (WARNING: image file is also removed)
 187
 188 server (Compute/Cyclades)
 189 -------------------------
 190
 191 .. code-block:: text
 192
 193     info      Detailed information on a Virtual Machine
 194     modify    Modify attributes of a virtual server
 195     create    Create a server (aka Virtual Machine)
 196     list      List virtual servers accessible by user
 197     reboot    Reboot a virtual server
 198     start     Start an existing virtual server
 199     shutdown  Shutdown an active virtual server
 200     delete    Delete a virtual server
 201     wait      Wait for server to finish [BUILD, STOPPED, REBOOT, ACTIVE]
 202
 203 Showcase: Create a server
 204 ^^^^^^^^^^^^^^^^^^^^^^^^^
 205
 206 .. code-block:: console
 207     :emphasize-lines: 1,4,21,35,44,62
 208
 209     [kamaki]: server
 210
 211     [server]: create -h
 212     usage: create --name NAME --flavor-id FLAVOR_ID --image-id IMAGE_ID
 213             [--personality PERSONALITY] [-h] [--config CONFIG] [--cloud CLOUD]
 214
 215     Create a server
 216
 217     optional arguments:
 218       -v, --verbose         More info at response
 219       --personality PERSONALITY
 220                             add a personality file
 221       -d, --debug           Include debug output
 222       -h, --help            Show help message
 223       -i, --include         Include protocol headers in the output
 224       --config CONFIG       Path to configuration file
 225       -s, --silent          Do not output anything
 226       --cloud CLOUD         Chose a cloud to connect to
 227
 228     * List all available images *
 229     [server]: /image compute list
 230     1395fdfb-51b4-419f-bb02-f7d632860611 Ubuntu Desktop LTS
 231     1580deb4-edb3-4496-a27f-7a246c4c0528 Ubuntu Desktop
 232     18a82962-43eb-4b32-8e28-8f8880af89d7 Kubuntu LTS
 233     6aa6eafd-dccb-422d-a904-67fe2bdde87e Debian Desktop
 234     6b5681e4-7502-46ae-b1e9-9fd837932095 maelstrom
 235     78262ee7-949e-4d70-af3a-85360c3de57a Windows Server 2012
 236     86bc2414-0fb3-4898-a637-240292243302 Fedora
 237     926ab1c5-2d85-49d4-aebe-0fce712789b9 Windows Server 2008
 238     b2dffe52-64a4-48c3-8a4c-8214cc3165cf Debian Base
 239     baf2321c-57a0-4a69-825d-49f49cea163a CentOS
 240     c1d27b46-d875-4f5c-b7f1-f39b5af62905 Kubuntu
 241
 242     * See details of flavor with id 1 *
 243     [server]: /flavor info 1
 244     SNF:disk_template:  drbd
 245     cpu              :  1
 246     disk             :  20
 247     id               :  1
 248     name             :  C1R1024D20
 249     ram              :  1024
 250
 251     * Create a debian server named 'My Small Debian Server'
 252     [server]: create --name='My Small Debian Server' --flavor-id=1 --image-id=b2dffe52-64a4-48c3-8a4c-8214cc3165cf
 253     adminPass:  L8gu2wbZ94
 254     created  :  2012-11-23T16:56:04.190813+00:00
 255     flavorRef:  1
 256     hostId   :
 257     id       :  11687
 258     imageRef :  b2dffe52-64a4-48c3-8a4c-8214cc3165cf
 259     metadata :
 260                os   :  debian
 261                users:  root
 262     name     :  My Small Debian Server
 263     progress :  0
 264     status   :  BUILD
 265     suspended:  False
 266     updated  :  2012-11-23T16:56:04.761962+00:00
 267
 268     * wait for server to build (optional) *
 269     [server]: wait 11687
 270     Server 11687 still in BUILD mode |||||||||||||||||    | 80%
 271     Server 11687 is now in ACTIVE mode
 272
 273 .. Note:: In kamaki shell, / is used to access commands from top-level
 274
 275 ip (Network/Cyclades)
 276 ---------------------
 277
 278 .. code-block:: text
 279
 280     info      Get details on a floating IP
 281     create    Reserve an IP on a network
 282     list      List reserved floating IPs
 283     delete    Unreserve an IP (also delete the port, if attached)
 284
 285 port (Network/Cyclades)
 286 -----------------------
 287
 288 .. code-block:: text
 289
 290     info      Get details about a port
 291     list      List all ports
 292     create    Create a new port (== connect server to network)
 293     modify    Modify the attributes of a port
 294     delete    Delete a port (== disconnect server from network)
 295     wait      Wait for port to finish [ACTIVE, DOWN, BUILD, ERROR]
 296
 297 Showcase: Reserve and attach IP to server
 298 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 299
 300 .. code-block:: text
 301
 302     * Enter port context *
 303     [kamaki]: port
 304
 305     * Reserve an IP and see servers and networks*
 306     [port]: /ip create
 307     123.456.78.9
 308     [port]: /server list
 309     42   My Windows Server
 310     43   My Linux Server
 311     [port]: /network list
 312     101  My Network 1
 313     102  My Network 2
 314
 315     * Attach IP to server
 316     [port]: port create --device-id=43 --network-id=101 --ip-address=123.456.78.9 --wait
 317     Creating new port 7 between server 43 and network 101
 318     Port 7 still in BUILD mode |||||||||||||||||    | 80%
 319     Port 7 is now in ACTIVE mode
 320
 321 .. Note:: In kamaki shell, / is used to access top-level command groups while
 322     working in command group contexts
 323
 324 network (Network/Cyclades)
 325 --------------------------
 326
 327 .. code-block:: text
 328
 329     info        Get details about a network
 330     disconnect  Disconnect a network from a device
 331     modify      Modify network attributes
 332     create      Create a new network
 333     list        List networks
 334     connect     Connect a network with a device (server or router)
 335     delete      Delete a network
 336
 337 Showcase: Connect a network to a VM
 338 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 339
 340 .. code-block:: console
 341     :emphasize-lines: 1,4,9,24,27,44
 342
 343     * Enter network context *
 344     [kamaki]: network
 345
 346     * List user-owned VMs *
 347     [network]: /server list
 348     11687 (My Small Debian Server)
 349     11688 (An Ubuntu server)
 350
 351     * Try network-connect (to get help) *
 352     [network]: connect
 353     Syntax error
 354     usage: connect <network id> <device id> [-s] [-h] [-i] [--config CONFIG]
 355
 356     Connect a server to a network
 357
 358     Syntax: connect  <server id> <network id>
 359       --config    :  Path to configuration file
 360       -d,--debug  :  Include debug output
 361       -h,--help   :  Show help message
 362       -i,--include:  Include protocol headers in the output
 363       -s,--silent :  Do not output anything
 364       -v,--verbose:  More info at response
 365
 366     * Connect VM with id 11687 to network with id 1409
 367     [network]: connect 11687 1409 --wait
 368     Creating port between network 1409 and server 11687
 369     New port: 8
 370
 371     * Get details on network with id 1409
 372     [network]: info 1409
 373       attachments:
 374                 8
 375       cidr    :  192.168.1.0/24
 376       cidr6   :  None
 377       created :  2012-11-23T17:17:20.560098+00:00
 378       dhcp    :  True
 379       gateway :  None
 380       gateway6:  None
 381       id      :  1409
 382       name    :  my network
 383       public  :  False
 384       status  :  ACTIVE
 385       type    :  MAC_FILTERED
 386       updated :  2012-11-23T17:18:25.095225+00:00
 387
 388     * Get connectivity details on VM with id 11687 *
 389     [network]: /server info 11687 --nics
 390     nic-11687-1
 391         ipv4       :  192.168.1.1
 392         ipv6       :  None
 393         mac_address:  aa:0f:c2:0b:0e:85
 394         network_id :  1409
 395         firewallProfile:  DISABLED
 396     nic-11687-0
 397         ipv4           :  83.212.106.111
 398         ipv6           :  2001:648:2ffc:1116:a80c:f2ff:fe12:a9e
 399         mac_address    :  aa:0c:f2:12:0a:9e
 400         network_id     :  1369
 401
 402 .. Note:: In kamaki shell, / is used to access top-level command groups while working in command group contexts
 403
 404 container (Storage/Pithos+)
 405 ---------------------------
 406
 407 .. code-block:: text
 408
 409     info      Get information about a container
 410     modify    Modify the properties of a container
 411     create    Create a new container
 412     list      List all containers, or their contents
 413     empty     Empty a container
 414     delete    Delete a container
 415
 416 group (Storage/Pithos+)
 417 -----------------------
 418
 419 .. code-block:: text
 420
 421     create    Create a group of users
 422     list      List all groups and group members
 423     delete    Delete a user group
 424
 425 sharer (Storage/Pithos+)
 426 ------------------------
 427
 428 .. code-block:: text
 429
 430     info      Details on a Pithos+ sharer account (default: current account)
 431     list      List accounts who share file objects with current user
 432
 433 file (Storage/Pithos+)
 434 ----------------------
 435
 436 .. code-block:: text
 437
 438     info      Get information/details about a file
 439     truncate  Truncate remote file up to size
 440     mkdir     Create a directory
 441     create    Create an empty file
 442     move      Move objects, even between different accounts or containers
 443     list      List all objects in a container or a directory object
 444     upload    Upload a file
 445     cat       Fetch remote file contents
 446     modify    Modify the attributes of a file or directory object
 447     append    Append local file to (existing) remote object
 448     download  Download a remove file or directory object to local file system
 449     copy      Copy objects, even between different accounts or containers
 450     overwrite Overwrite part of a remote file
 451     delete    Delete a file or directory object
 452
 453 Showcase: Upload and download a file
 454 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 455
 456 .. code-block:: console
 457     :emphasize-lines: 1,7,11,16,21,29,33,37,41,44,51,55,60,64
 458
 459     * Create a random binarry file at current OS path *
 460     [kamaki]: !dd bs=4M if=/dev/zero of=rndm_local.file count=5
 461     5+0 records in
 462     5+0 records out
 463     20971520 bytes (21 MB) copied, 0.016162 s, 1.3 GB/s
 464
 465     * Enter file context *
 466     [kamaki]: file
 467
 468
 469     * Check local file *
 470     [file]: !ls -lh rndm_local.file
 471     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
 472
 473
 474     * Create two containers *
 475     [file]: /container create mycont1
 476     [file]: /container create mycont2
 477
 478
 479     * List accessible containers *
 480     [file]: /container list
 481     1. mycont1 (0B, 0 objects)
 482     2. mycont2 (0B, 0 objects)
 483     3. pithos (0B, 0 objects)
 484     4. trash (0B, 0 objects)
 485
 486
 487     * Upload local file to 1st container *
 488     [file]: upload /mycont1/rndm_local.file
 489
 490
 491     * Check if file has been uploaded *
 492     [file]: list /mycont1
 493     1.    20M rndm_local.file
 494
 495     * Create directory mydir on second container *
 496     [file]: mkdir /mycont2/mydir
 497
 498     * Move file from 1st to 2nd container (and in the directory) *
 499     [file]: move /mycont1/rndm_local.file /mycont2/mydir/rndm_local.file
 500
 501     * Check contents of both containers *
 502     [file]: list /mycont1
 503     [file]: list /mycont2
 504     1.      D mydir/
 505     2.    20M mydir/rndm_local.file
 506
 507     * Copy file from 2nd to 1st container, with a new name *
 508     [file]: copy /mycont2/mydir/rndm_local.file /mycont1/rndm_remote.file
 509
 510     * Check pasted file *
 511     [file]: list /mycont1
 512     1.    20M rndm_remote.file
 513
 514     * Download pasted file to local file system *
 515     [file]: download /mycont1/rndm_remote.file
 516     Downloading: |||||||||||||||||   | 72%
 517
 518     * Check if file is downloaded and if it is the same to original *
 519     [file]: !ls -lh *.file
 520     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:36 rndm_local.file
 521     -rw-rw-r-- 1 ******** ******** 20M Nov 26 15:42 rndm_remote.file
 522     [file]: !diff rndm_local.file rndm_remote.file
 523
 524 .. Note:: In kamaki shell, ! is used to execute OS shell commands (e.g., bash)