Changes between Initial Version and Version 1 of Usage2/UserDocumentation

Timestamp:

05/06/16 08:58:10 (8 years ago)

Author:

jaap

Comment:

--

Usage2/UserDocumentation

@@ +1 @@
+[[PageOutline]]
+
+= User Documentation =
+
+CMT can be used with different user interfaces:
+
+ Web Interface::
+   An easy-to-use, self explainable, interface based on Django Admin. You only need a webbrowser to use this interface.
+ Command Line Interface (CLI)::
+   A less-easy-to-use interface which could be used to make mass-updates. The CLI offers the user some powerful functions which aren't possible on the web-interface. To use this interface you need to [Usage2/Quickstart#InstallCMT install CMT] on the computer you're using.
+
+'''Please keep in mind:''' Both interfaces are lacking of an undo-function, so be careful when you're about to make any changes in the data you've stored in CMT.
+
+
+= Web-interface =
+
+The web-interface can be opened in any regular web-browser.
+Ask your administrator for its address.
+Once you open the web-interface, a login-page should appear where you have to issue your credentials.
+
+From there you'll be able to add objects to the database, explore objects in the database, change objects in the database, or delete objects from the database.
+It's meant as a intuitive easy-to-use interface, with advanced Create-Read-Update-Delete (CRUD) functionalities.
+It makes you able to quickly explore the [wiki:/Data/Datastructure data stored in CMT], or act on the data.
+The most important entities you can act on are:
+ Clusters::
+   A cluster could be described as a collection of hardware, connected to each other through one or more networks.
+ Racks::
+   A rack is a cabinet that houses hardware like servers and switches.
+   It has multiple slots to mount hardware.
+   These slots identify the physical location of your hardware.
+ Equipment::
+   Hardware units like (virtual) servers, switches, PDU's, etc.
+   It could be 'any piece of hardware with a powercable attached to it'.
+ Networks::
+   Networks defined by their (IP) address space.
+   The addresses in the address space of a network each are related to an interface.
+ Interfaces::
+   Network interfaces for input/output, thus any kind of card or (virtual) adapter which can have a network-cable plugged into it, and has a hardware address (like a MAC-address).
+   Most obvious example is a regular 100/1000Mbit NIC, but it could be something like an !InfiniBand interface card, or an out-of-band management adapter.
+   Many network interfaces are related to a single piece of hardware, and a single network.
+
+= Command Line Interface =
+
+To use the Command Line Interface has to be installed on your system. If you issue the command `cmt` you'll get the usage info:
+{{{
+user@host$ cmt
+usage: cmt [-h] [--dry-run] [--verbose | --quiet] [--version]
+           [--config-file CONFIG_FILE]
+           {create,read,update,delete,parse} ...
+cmt: error: too few arguments
+
+}}}
+
+More information about the options can be read in the following subsections. For each option we'll give one or more use cases as an example.
+
+
+== CRUD(P) options ==
+
+Just like the web-interface, the CLI can be used for CRUD-functionalities (Create, Read, Update, Delete) too. However, the implementation of the CLI is much more powerful, since it can be used to do things with multiple objects at once, and can be done from shell-scripts.
+
+=== Create object: `create` ===
+
+Use this option to add a new object of a given entity to the database. You have to specify the entity and assign values to its fields by providing assignments as extra arguments. The syntax is as follows:
+
+{{{
+cmt create <entity> --set <assignments>
+}}}
+
+==== Use case ====
+
+'''You want to add a new server, and its interfaces'''
+
+As an example we'll add a server (!PowerEdge M610) to the 1st position in rack 1 of the Lisa-cluster. The server will be used as a test- and computenode, and has the following interfaces:
+
+|| ''Interface'' || ''network'' || ''MAC-address'' ||
+|| Gigabit || lisa admin || 00:00:00:00:00:01 ||
+|| iDRAC6 || lisa consoles || 00:00:00:00:00:03 ||
+
+{{{
+user@host$ cmt create equipment --set 'cluster=Lisa' 'label=jaap' rack=35 firs_slot=35 specifications="PowerEdge M620"
+
+user@host$ cmt --add interface host=r1n1 network='lisa admin' iftype='Gigabit' hwaddress='00:00:00:00:00:01'
+
+user@host$ cmt --add interface host=r1n1 network='lisa consoles' iftype='iDRAC6' hwaddress='00:00:00:00:00:03'
+}}}
+
+=== Read object(s): `read` ===
+
+Use this option to list existing objects in the database. You have to specify the entity, and filter objects you want to list by providing a query. The syntax is as follows:
+
+{{{
+cmt_sara read <entity> --get <query>
+}}}
+
+==== Use case ====
+
+'''If you need to figure out where a machine -- in this case `test3` -- is physically hosted:'''
+
+When an engineer has to fix a node you need to tell him the location of the node. This information shall be listed by issuing the following command:
+
+{{{
+user@host$ cmt read equipment label=test3
+}}}
+
+The output of this command looks like:
+
+{{{
+{
+    "count": 1,
+    "next": null,
+    "previous": null,
+    "results": [
+        {
+            "cluster": "Lisa",
+            "created_on": "2016-05-06T08:19:54.044",
+            "first_slot": 35,
+            "interfaces": [],
+            "label": "jaap",
+            "note": "",
+            "owner": null,
+            "rack": "35",
+            "role": [
+                "testnode"
+            ],
+            "seller": null,
+            "serial_number": null,
+            "specifications": "PowerEdge M620",
+            "state": "unknown",
+            "updated_on": "2016-05-06T08:39:32.776",
+            "url": "https://cmt.surfsara.nl/api/v1/equipment/5198/",
+            "warranty": null,
+            "warranty_tag": null
+        }
+    ]
+}
+}}}
+
+=== Update object(s): `update` ===
+
+Use this option to change fields of one or more objects in the database. You have to specify the entity, filter objects you want to change by providing a query, and assign new values to their fields by providing assignments as extra arguments. The syntax is as follows:
+
+
+TODO 
+{{{
+cmt 
+}}}
+
+
+=== Delete object(s): `delete` ===
+
+Use this option to remove objects from the database. You have to specify the entity, and filter objects you want to remove by providing a query. The syntax is as follows:
+
+{{{
+cmt delete <entity> --get <query>
+}}}
+
+==== Use case ====
+
+'''You have removed a server from a rack:'''
+
+For example node 'jaap' in rack 35:
+
+{{{
+user@host$ cmt delete equipment --get 'cluster=Lisa' 'label=jaap' 'rack=35'
+{u'count': 1,
+ u'next': None,
+ u'previous': None,
+ u'results': [{u'cluster': u'Lisa',
+               u'created_on': u'2016-05-06T08:19:54.044',
+               u'first_slot': 35,
+               u'interfaces': [],
+               u'label': u'jaap',
+               u'note': u'',
+               u'owner': None,
+               u'rack': u'35',
+               u'role': [u'testnode'],
+               u'seller': None,
+               u'serial_number': None,
+               u'specifications': u'PowerEdge M620',
+               u'state': u'unknown',
+               u'updated_on': u'2016-05-06T08:39:32.776',
+               u'url': u'https://cmt.surfsara.nl/api/v1/equipment/5198/',
+               u'warranty': None,
+               u'warranty_tag': None}]}
+[DELETE] You are about to delete: 1 object(s). Are you sure ([N]/Y)?: y
+[DELETING] 1 of 1
+[LOGIN] Authorization required
+[LOGIN] Username: jaap
+[LOGIN] Password:
+[SUCCESS] Succefully deleted 1 object(s)
+}}}
+
+As you can see there will be asked for confirmation by default.
+
+
+== Other options ==
+
+
+
+=== Generate a config-file: `parse` ===
+
+Render a template to generate a config-file or a report. Use the following syntax:
+
+{{{
+cmt parse <templatename>
+}}}
+
+By default your templates can be found in your (virtual) environment in de directory `/etc/cmt/templates`.
+
+
+
+More information about how to write your own templates can be found at a [wiki:Usage/TemplatingDocumentation separate page about the template language].