Changes between Version 3 and Version 4 of Usage/UserDocumentation

Timestamp:

05/31/12 14:46:39 (12 years ago)

Author:

sil

Comment:

documented options of cmt client

Usage/UserDocumentation

@@ -40 +40 @@
 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 [options]
 
@@ -49 +50 @@
   --script              
   -a ENTITY, --add=ENTITY
-                        Add an object of given ENTITY.              arguments:
-                        set <ASSIGNMENTS>              The object will get
-                        values according to the given assignments.
-                        Assignments could be formed like
-                        [<FK>__]<attr>=<value>
+                        Add an object of the given ENTITY. Extra arguments
+                        should be given like `set ASSIGNMENTS`, where
+                        ASSIGNMENTS are formatted like `ATTR=VAL`
   -c ENTITY, --change=ENTITY
-                        Change value(s) of object(s) of given ENTITY.
-                        arguments:   get <QUERY> set <ASSIGNMENTS>
-                        The query, which consists out of one or more terms, is
-                        used to make             a selection of objects to
-                        change. These objects will be changed
-                        according to the given assignments.
+                        Change value(s) of object(s) of the given ENTITY.
+                        Arguments should be given like `get QUERY set
+                        ASSIGNMENTS`, where both QUERY and ASSIGNMENTS consist
+                        out of one or more terms formatted like `ATTR=VAL`.
+                        Only objects matching QUERY will be changed according
+                        to the given ASSIGNMENTS
   -g TEMPLATE, --generate=TEMPLATE
-                        Render the given template
-  -l ENTITY [ATTRIBUTE=VALUE], --list=ENTITY [ATTRIBUTE=VALUE]
-                        List object(s) of the given ENTITY.
-                        arguments:   get <QUERY>              The query, which
-                        consists out of one or more terms, is used to make
-                        a selection of objects to list.
-  -r ENTITY [ATTRIBUTE=VALUE], --remove=ENTITY [ATTRIBUTE=VALUE]
-                        Remove objects which reflect the given query
+                        Render the given TEMPLATE, and store the result if
+                        specified
+  -l ENTITY, --list=ENTITY
+                        List object(s) of the given ENTITY. Arguments should
+                        be given like `get QUERY`, where QUERY consists out of
+                        one or more terms formatted like `ATTR=VAL`
+  -r ENTITY, --remove=ENTITY
+                        Remove object(s) of the given ENTITY. Arguments should
+                        be given like `get QUERY`, where QUERY consists out of
+                        one or more terms formatted like `ATTR=VAL`. Only
+                        objects matching QUERY will be listed
   -v, --verbose         
 }}}
 
-
-== Add object(s): `-a, --add` ==
-=== Syntax ===
-=== Use case ===
+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.
+
+
+== Add object: `-a, --add` ==
+
+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 --add <entity> <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 ||
+|| !InfiniBand || lisa infiniband || 00:00:00:00:00:02 ||
+|| iDRAC6 || lisa consoles || 00:00:00:00:00:03 ||
+
+{{{
+user@host$ cmt --add hardwareunit cluster=Lisa role=computenode role=testnode specifications='PowerEdge M610' rack=1 first_slot=1
+
+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 infiniband' iftype='InfiniBand' hwaddress='00:00:00:00:00:02'
+
+user@host$ cmt --add interface host=r1n1 network='lisa consoles' iftype='iDRAC6' hwaddress='00:00:00:00:00:03'
+}}}
+
+
 == Change object(s): `-c, --change` ==
-=== Syntax ===
-=== Use case ===
-== Generate a configfile: `-g, --generate` ==
-=== Syntax ===
-=== Use case ===
+
+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:
+
+{{{
+sara_cmt --change <entity> [get] <query> set <assignments>
+}}}
+
+=== Use case ===
+'''You have to change an existing address:'''
+
+{{{
+user@host$ cmt --change address get address='Kruislaan 415' set address='Science Park 121' postalcode='1098 XG'
+}}}
+
+'''Or maybe a motherboard has been replaced, so the MAC-addresses of the onboard interfaces have been changed:'''
+
+|| ''Interface'' || ''Old MAC'' || ''New MAC'' ||
+|| Gigabit || 00:23:AE:FD:C9:00 || 00:26:B9:F9:95:34 ||
+|| iDRAC6 || 00:23:AE:FB:C7:DD || A4:BA:DB:00:31:F6 ||
+
+{{{
+user@host$ cmt --change interface get hwaddress=00:23:AE:FD:C9:00 set hwaddress=00:26:B9:F9:95:34
+
+user@host$ cmt --change interface get hwaddress=00:23:AE:FB:C7:DD set hwaddress=A4:BA:DB:00:31:F6
+}}}
+
+In both commands you'll query for the interface with the old MAC-address, and overwrite the value of the hwaddress-field with the new MAC-address.
+
+Since you know in which machine the motherboard has been replaced -- in this case `r34n26` -- it might be easier to issue a command like:
+
+{{{
+user@host$ cmt --change interface get host=r34n26 iftype=Gigabit set hwaddress=00:26:B9:F9:95:34
+
+user@host$ cmt --change interface get host=r34n26 iftype=iDRAC6 set hwaddress=A4:BA:DB:00:31:F6
+}}}
+
+This will only work when the machine contains a single Gigabit-interface, as well as a single iDRAC6-interface. In this case you don't need to know the old MAC-addresses.
+
+'''You want to add the service-tags to new Dell-hardware:'''
+
+For example new chassis in rack 2, 13, and 36:
+
+{{{
+user@host$ for rack in 2 13 36
+> do
+>   for cmc in a b
+>   do
+>     svctag=`sararac -c getsvctag dr-r${rack}cmc-${cmc} | sed -rn 's/^Chassis.*([A-Z0-9]{7})$/\1/p'`
+>     echo saving warranty tag ${svctag} to r${rack}cmc-${cmc}
+>     cmt --script --change hardwareunit get label=r${rack}cmc-${cmc} set warranty_tag=${svctag}
+>   done
+> done
+}}}
+
+And all hardware in these chassis:
+
+{{{
+user@host$ for rack in 2 13 36
+> do
+>   for node in `seq 1 32`
+>   do
+>     svctag=`sararac -c getsvctag dr-r${rack}n${node} | sed -rn 's/^.*([A-Z0-9]{7})$/\1/p'`
+>     echo saving warranty tag ${svctag} to r${rack}n${node}
+>     cmt --script --change hardwareunit get rack=${rack} first_slot=${node} set warranty_tag=${svctag}
+>   done
+> done
+}}}
+
+
+== Generate a config-file: `-g, --generate` ==
+
+Render a template to generate a config-file or a report. Use the following syntax:
+
+{{{
+sara_cmt --generate <templatename>
+}}}
+
+=== Use case ===
+
+'''When you want to generate the cfrun_hosts file of the Clearspeed cluster:'''
+
+{{{
+user@host$ cmt --generate cfrun_hosts.clearspeed
+}}}
+Which generates the cfrun_hosts file and stores the following content at `/usr/sara/etc/cfengine/rc.hosts.clearspeed`:
+
+{{{
+#
+# This file is automagicly generated by CMT
+#
+#             SARA - Computing and Networking Services
+# Date      : Tue, 15 Jun 2010
+# Version   : CMT CLI 1.0
+# Generated : Thu, 15 Jul 2010 09:20:27 +0200
+#
+# SVN:
+#       $Id:$
+#       $URL:$
+#
+
+
+outputdir=/data/cfengine/output/clearspeed
+maxchild=8
+login1
+gb-r50n1.irc.sara.nl
+gb-r50n2.irc.sara.nl
+gb-r50n3.irc.sara.nl
+gb-r50n4.irc.sara.nl
+gb-r50n5.irc.sara.nl
+gb-r50n6.irc.sara.nl
+gb-r50n7.irc.sara.nl
+gb-r50n8.irc.sara.nl
+gb-r51n1.irc.sara.nl
+gb-r51n2.irc.sara.nl
+gb-r51n3.irc.sara.nl
+gb-r51n4.irc.sara.nl
+gb-r51n5.irc.sara.nl
+gb-r51n6.irc.sara.nl
+gb-r51n7.irc.sara.nl
+gb-r51n8.irc.sara.nl
+}}}
+
+
 == List object(s): `-l, --list` ==
-=== Syntax ===
-=== Use case ===
+
+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 --list <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 --list hardwareunit label=test3
+}}}
+
+The output of this command looks like:
+
+{{{
+ .---[  test3  ]---
+ : cluster        : LDAP/CUA
+ : address        : Amsterdam - Science Park 121
+ : room           : S142A
+ : rack           : rack AD38
+ : first_slot     : 23
+ : specifications : PowerEdge 1950 (Dell bv)
+ : roles          : administration
+ : in_support     : True
+ '---
+}}}