Recent changes to Client Tool

Client Tool modified by Mark R. Bannister

Mark R. Bannister — Wed, 11 Nov 2015 11:38:01 -0000

--- v5
+++ v6
@@ -66,7 +66,7 @@
 ------ | -----------
 `-D` (`--debug`) | Turn on debug mode.
 `-e` (`--recurse`) | Recurse member netgroups.  This is used in conjunction with `dbis getnetgrent` and will expand any included netgroups to produce a list of tuples only.
-`-h` (`--help`) *`[command]`* | Display help message and list all valid subcommands.  If a specific command is given, display help on the specified command.
+`-h` (`--help`) *`[command]`* | Display help message.  If a command is given, display help on the specified command.  If command is `all`, list all server commands.
 `-j` (`--json`) | Display raw JSON output.
 `-l` (`--long`) | Display long output.  This will display all of the data contained in the LDAP entry in a format similar to LDIF.  The default is to display the data in a format similar to the `getent` command.
 `-n` (`--nss`) | Set output format to NSS-style, i.e. similar to the `getent` command.  This is the default behaviour.

Client Tool modified by Mark R. Bannister

Mark R. Bannister — Wed, 11 Nov 2015 11:35:48 -0000

--- v4
+++ v5
@@ -5,44 +5,12 @@

 The client tool can display maps in the same format as the system-supplied `getent` command, although it only includes data from DBIS and not from the other sources defined in `/etc/nsswitch.conf`.  It is also more powerful than the `getent` command, optionally displaying more information including those databases not supported by NSS as well as LDAP object class and attribute information, source DNs and time the data was loaded into the cache.

-The `dbis` command takes a subcommmand that identifies the database to query and the type of information requested.  The subcommand is similarly named to the system C API used for querying NSS.  For example, `getpwnam()` is the name of the C function used to get password entries, and `dbis getpwnam` is the command that queries password entries from DBIS.
-
-A full list of supported subcommands is obtained by running `dbis -h`:
-
-~~~~
-$ dbis -h
-
-Syntax: dbis [-D|--debug] [-e|--recurse] [-j|--json] [-l|--long] [-n|--nss] \
-                 [-o|--sort] [-p|--pprint] [-r|--raw] [-s|--server ] \
-                 [-t|--stream] [-w|--width <width>]  <arguments>
-        dbis -h|--help []
-        dbis -v|--version
-
-Connects to DBIS cache manager and sends given command and arguments.
-
-Options:
-        -D (--debug)     turn on debugging.
-        -e (--recurse)   recurse member netgroups.
-        -h (--help) []
-                         display this help message.  If a command is also
-                         given, display help on specified command.
-        -j (--json)      display raw JSON output.
-        -l (--long)      display long output.
-        -n (--nss)       set output format to NSS-style (default).
-        -o (--sort)      sort output.
-        -p (--pprint)    pretty-print non-string attribute data encountered
-                         when rendering long or raw output.
-        -r (--raw)       display raw output.
-        -s (--server) 
-                         connect to DBIS server on this address, can be
-                         in format <host>:<port> or a pathname to a UNIX
-                         domain socket.
-        -t (--stream)    set output format to data stream (binary).
-        -v (--version)   display program version and copyright message.
-        -w (--width) <width>
-                         override terminal width with alternative value.
-
-Valid server commands are:
+The `dbis` command takes a subcommand that identifies the database to query and the type of information requested.  The subcommand is similarly named to the system C API used for querying NSS.  For example, `getpwnam()` is the name of the C function used to get password entries, and `dbis getpwnam` is the command that queries password entries from DBIS.
+
+A full list of supported subcommands is obtained by running `dbis -h all`:
+
+~~~~
+$ dbis -h all
     getautocfg         lookup in dbisAutomountConfig database
     getautomount       lookup in automount database
     getbootbyaddr      lookup in bootparams database (by ipv4Address)
@@ -83,7 +51,7 @@
     getrpcbynumber     lookup in rpc database (by rpcNumber)
     getrpccfg          lookup in dbisRpcConfig database
     getservbyname      lookup in services database
-    getservbyport      lookup in services database (by ipPortNumber)
+    getservbyport      lookup in services database (by ipServicePort)
     getservcfg         lookup in dbisServiceConfig database
     innetgr            lookup in netgroup database
     innetgr2           lookup in netgroup database

Client Tool modified by Mark R. Bannister

Mark R. Bannister — Tue, 14 Apr 2015 09:50:07 -0000

--- v3
+++ v4
@@ -12,9 +12,9 @@
 ~~~~
 $ dbis -h

-Syntax: dbis [-D|--debug] [-e|--recurse] [-l|--long] [-n|--nss] [-o|--sort] \
-                    [-p|--pprint] [-r|--raw] [-s|--server ] \
-                    [-t|--stream] [-w|--width <width>]  <arguments>
+Syntax: dbis [-D|--debug] [-e|--recurse] [-j|--json] [-l|--long] [-n|--nss] \
+                 [-o|--sort] [-p|--pprint] [-r|--raw] [-s|--server 
] \
+                 [-t|--stream] [-w|--width <width>]  <arguments>
         dbis -h|--help []
         dbis -v|--version

@@ -26,6 +26,7 @@
         -h (--help) []
                          display this help message.  If a command is also
                          given, display help on specified command.
+        -j (--json)      display raw JSON output.
         -l (--long)      display long output.
         -n (--nss)       set output format to NSS-style (default).
         -o (--sort)      sort output.
@@ -98,10 +99,12 @@
 `-D` (`--debug`) | Turn on debug mode.
 `-e` (`--recurse`) | Recurse member netgroups.  This is used in conjunction with `dbis getnetgrent` and will expand any included netgroups to produce a list of tuples only.
 `-h` (`--help`) *`[command]`* | Display help message and list all valid subcommands.  If a specific command is given, display help on the specified command.
+`-j` (`--json`) | Display raw JSON output.
 `-l` (`--long`) | Display long output.  This will display all of the data contained in the LDAP entry in a format similar to LDIF.  The default is to display the data in a format similar to the `getent` command.
 `-n` (`--nss`) | Set output format to NSS-style, i.e. similar to the `getent` command.  This is the default behaviour.
 `-o` (`--sort`) | Sort output.  This sorts entries in dictionary order.  If displaying long output with the `-l` option, the attributes within a single entry will also be sorted.
 `-p` (`--pprint`) | Pretty-print non-string attribute data encountered when rendering long or raw output.
+`-r` (`--raw`) | Display raw output.
 `-s` (`--server`) *`address`* | Connect to DBIS server on this address.  Can be in the format `host:port` or a pathname to a UNIX domain socket.  The default is `/var/run/dbis/client`.
 `-t` (`--stream`) | Set output format to data stream (binary) mode.  This is the output format used by the NSS library over the `/var/run/dbis/nss` socket.
 `-v` (`--version`) | Display program version and copyright message, then exit.
@@ -126,6 +129,7 @@

                 DN: en=mark,ou=passwd,ou=sales,o=infra
       Last updated: Fri Jan  9 07:28:03 2015 (422.9773 seconds ago)
+ Configuration map: cn=passwd,en=sales.corp,ou=domain-mappings,o=infra
        objectClass: top
        objectClass: inetOrgPerson
        objectClass: posixUserAccount
@@ -144,11 +148,12 @@

 ~~~~
 $ dbis -r getpwnam mark
-(('en=mark,ou=passwd,ou=sales,o=infra', {'en': ['mark'], 'displayName':
-['Bannister, Mark'], 'cn': ['Mark'], 'objectClass': ['top', 'inetOrgPerson',
-'posixUserAccount'], 'loginShell': ['/bin/bash'], 'uidNumber': ['801'],
-'gidNumber': ['900'], 'sn': ['Bannister'], 'homeDirectory': ['/home/mark'],
-'dbisMapGecos': ['displayName']}), 1420788483.685508, 900)
+(('en=mark,ou=passwd,ou=sales,o=infra', {{'_cfgmap': ['cn=passwd,en=sales.corp,
+ou=domain-mappings,o=infra'], 'en': ['mark'], 'displayName': ['Bannister, Mark'],
+'cn': ['Mark'], 'objectClass': ['top', 'inetOrgPerson', 'posixUserAccount'],
+'loginShell': ['/bin/bash'], 'uidNumber': ['801'], 'gidNumber': ['900'],
+'sn': ['Bannister'], 'homeDirectory': ['/home/mark'], 'dbisMapGecos':
+['displayName']}), 1420788483.685508, 900)
 ~~~~

 Displaying a single entry from the passwd map in raw format with pretty-print:
@@ -156,7 +161,8 @@
 ~~~~
 $ dbis -rp getpwnam mark
 (('en=mark,ou=passwd,ou=sales,o=infra',
-  {'cn': ['Mark'],
+  {'_cfgmap': ['cn=passwd,en=sales.corp,ou=domain-mappings,o=infra'],
+   'cn': ['Mark'],
    'dbisMapGecos': ['displayName'],
    'displayName': ['Bannister, Mark'],
    'en': ['mark'],

Client Tool modified by Mark R. Bannister

Mark R. Bannister — Fri, 09 Jan 2015 17:17:45 -0000

--- v2
+++ v3
@@ -144,7 +144,11 @@

 ~~~~
 $ dbis -r getpwnam mark
-(('en=mark,ou=passwd,ou=sales,o=infra', {'en': ['mark'], 'displayName': ['Bannister, Mark'], 'cn': ['Mark'], 'objectClass': ['top', 'inetOrgPerson', 'posixUserAccount'], 'loginShell': ['/bin/bash'], 'uidNumber': ['801'], 'gidNumber': ['900'], 'sn': ['Bannister'], 'homeDirectory': ['/home/mark'], 'dbisMapGecos': ['displayName']}), 1420788483.685508, 900)
+(('en=mark,ou=passwd,ou=sales,o=infra', {'en': ['mark'], 'displayName':
+['Bannister, Mark'], 'cn': ['Mark'], 'objectClass': ['top', 'inetOrgPerson',
+'posixUserAccount'], 'loginShell': ['/bin/bash'], 'uidNumber': ['801'],
+'gidNumber': ['900'], 'sn': ['Bannister'], 'homeDirectory': ['/home/mark'],
+'dbisMapGecos': ['displayName']}), 1420788483.685508, 900)
 ~~~~

 Displaying a single entry from the passwd map in raw format with pretty-print:

Client Tool modified by Mark R. Bannister

Mark R. Bannister — Fri, 09 Jan 2015 17:07:04 -0000

--- v1
+++ v2
@@ -96,14 +96,14 @@
 Option | Description
 ------ | -----------
 `-D` (`--debug`) | Turn on debug mode.
-`-e` (`--recurse`) | Recurse member netgroups.  This is used in conjunction with `dbis getnetgrent` and will replace expand any included netgroups to produce a list tuples only.
+`-e` (`--recurse`) | Recurse member netgroups.  This is used in conjunction with `dbis getnetgrent` and will expand any included netgroups to produce a list of tuples only.
 `-h` (`--help`) *`[command]`* | Display help message and list all valid subcommands.  If a specific command is given, display help on the specified command.
 `-l` (`--long`) | Display long output.  This will display all of the data contained in the LDAP entry in a format similar to LDIF.  The default is to display the data in a format similar to the `getent` command.
 `-n` (`--nss`) | Set output format to NSS-style, i.e. similar to the `getent` command.  This is the default behaviour.
 `-o` (`--sort`) | Sort output.  This sorts entries in dictionary order.  If displaying long output with the `-l` option, the attributes within a single entry will also be sorted.
 `-p` (`--pprint`) | Pretty-print non-string attribute data encountered when rendering long or raw output.
 `-s` (`--server`) *`address`* | Connect to DBIS server on this address.  Can be in the format `host:port` or a pathname to a UNIX domain socket.  The default is `/var/run/dbis/client`.
-`-t` (`--stream`) | Set output format to data stream (binary) mode.  This is the output format used by the NSS library over the `/var/run/dbis/nss` socket
+`-t` (`--stream`) | Set output format to data stream (binary) mode.  This is the output format used by the NSS library over the `/var/run/dbis/nss` socket.
 `-v` (`--version`) | Display program version and copyright message, then exit.
 `-w` (`--width`) *`width`* | Override terminal width with alternative value.  This affects how raw data is pretty-printed when used alongside the `-p` option.

@@ -177,3 +177,74 @@
 23.0.7.1        peg.aja.com
 10.11.12.14     kilcher
 ~~~~
+
+Listing contents of `auto_master` map:
+
+~~~~
+$ dbis getautomount auto_master
+/home   auto_home       -nobrowse
+/qa     qa
+/media  media
+/-      auto_direct
+~~~~
+
+Listing contents of `auto_home` map:
+
+~~~~
+$ dbis getautomount auto_home
+fred            surbiton:/export/home/&
+sheila          surbiton:/export/home/&
+*               ditton:/export/home/&
+~~~~
+
+Looking up all custom available custom maps:
+
+~~~~
+$ dbis getcustom
+console
+tracks
+weblinks
+~~~~
+
+Looking up a specific entry in one custom map:
+
+~~~~
+$ dbis getcustom console chekov
+chekov  111 ssh
+~~~~
+
+Displaying configuration map objects for the services database:
+
+~~~~
+$ dbis -l getservcfg
+          Database: dbisServiceConfig
+           Command: getservcfg
+    Time retrieved: Fri Jan  9 17:05:56 2015
+ DB last refreshed: Fri Jan  9 16:59:28 2015 (388.6844 seconds ago)
+
+                DN: cn=services,en=sales.corp,ou=domain-mappings,o=infra
+      Last updated: Fri Jan  9 16:59:28 2015 (388.6849 seconds ago)
+       objectClass: top
+       objectClass: dbisMapConfig
+       objectClass: dbisServiceConfig
+         dbisMapDN: ou=services,o=infra
+       description: Primary services database
+     dbisMapFilter: objectClass=ipServiceObject
+                cn: services
+
+                DN: cn=services-legacy,ou=rfc2307,en=sales.corp,ou=domain-mappings,o=infra
+      Last updated: Fri Jan  9 16:59:28 2015 (388.6852 seconds ago)
+       objectClass: top
+       objectClass: dbisMapConfig
+       objectClass: dbisServiceConfig
+       dbisMapAttr: ipProtocolName=ipServiceProtocol
+       dbisMapAttr: ipPortNumber=ipServicePort
+       dbisMapAttr: en=cn
+                cn: services-legacy
+      dbisMapClass: ipServiceObject=ipService
+     dbisMapFilter: objectClass=ipService
+         dbisMapDN: ou=rfc2307,o=infra
+       description: services database entries that use the legacy RFC2307 schema
+~~~~
+
+For more information on the other components of DBIS, see [Using DBIS].

Client Tool modified by Mark R. Bannister

Mark R. Bannister — Fri, 09 Jan 2015 07:39:47 -0000

Client Tool

The dbis client tool can be used to query any of the DBIS databases and display the output in a variety of formats. It can also be used for displaying configuration map entries.

The client tool can display maps in the same format as the system-supplied getent command, although it only includes data from DBIS and not from the other sources defined in /etc/nsswitch.conf. It is also more powerful than the getent command, optionally displaying more information including those databases not supported by NSS as well as LDAP object class and attribute information, source DNs and time the data was loaded into the cache.

The dbis command takes a subcommmand that identifies the database to query and the type of information requested. The subcommand is similarly named to the system C API used for querying NSS. For example, getpwnam() is the name of the C function used to get password entries, and dbis getpwnam is the command that queries password entries from DBIS.

A full list of supported subcommands is obtained by running dbis -h:

$ dbis -h

Syntax: dbis [-D|--debug] [-e|--recurse] [-l|--long] [-n|--nss] [-o|--sort] \
                    [-p|--pprint] [-r|--raw] [-s|--server <address>] \
                    [-t|--stream] [-w|--width <width>] <command> <arguments>
        dbis -h|--help [<command>]
        dbis -v|--version

Connects to DBIS cache manager and sends given command and arguments.

Options:
        -D (--debug)     turn on debugging.
        -e (--recurse)   recurse member netgroups.
        -h (--help) [<command>]
                         display this help message.  If a command is also
                         given, display help on specified command.
        -l (--long)      display long output.
        -n (--nss)       set output format to NSS-style (default).
        -o (--sort)      sort output.
        -p (--pprint)    pretty-print non-string attribute data encountered
                         when rendering long or raw output.
        -r (--raw)       display raw output.
        -s (--server) <address>
                         connect to DBIS server on this address, can be
                         in format <host>:<port> or a pathname to a UNIX
                         domain socket.
        -t (--stream)    set output format to data stream (binary).
        -v (--version)   display program version and copyright message.
        -w (--width) <width>
                         override terminal width with alternative value.

Valid server commands are:
    getautocfg         lookup in dbisAutomountConfig database
    getautomount       lookup in automount database
    getbootbyaddr      lookup in bootparams database (by ipv4Address)
    getbootbyaddr6     lookup in bootparams database (by ipv6Address)
    getbootbyhost      lookup in bootparams database (by rn)
    getbootcfg         lookup in dbisBootConfig database
    getbootparam       lookup in bootparams database
    getcustom          lookup in custom database
    getcustomcfg       lookup in dbisCustomConfig database
    getdomaincfg       lookup in dbisDomainObject database
    getether           lookup in ethers database
    getetherbyaddr     lookup in ethers database (by ipv4Address)
    getetherbyaddr6    lookup in ethers database (by ipv6Address)
    getetherbyhost     lookup in ethers database (by rn)
    getethercfg        lookup in dbisEtherConfig database
    getgrbymem         lookup group by membership
    getgrcfg           lookup in dbisGroupConfig database
    getgrgid           lookup in group database (by gidNumber)
    getgrnam           lookup in group database
    gethostbyaddr      lookup in hosts database (by ipv4Address)
    gethostbyaddr6     lookup in hosts database (by ipv6Address)
    gethostbyname      lookup in hosts database
    gethostcfg         lookup in dbisHostConfig database
    getnetbyaddr       lookup in networks database (by ipNetworkNumber)
    getnetbyname       lookup in networks database
    getnetcfg          lookup in dbisNetworkConfig database
    getnetgrcfg        lookup in dbisNetgroupConfig database
    getnetgrent        lookup in netgroup database
    getnetsvcfg        lookup in dbisNetserviceConfig database
    getnetsvent        lookup in netservice database
    getprotobyname     lookup in protocols database
    getprotobynumber   lookup in protocols database (by ipProtocolNumber)
    getprotocfg        lookup in dbisProtocolConfig database
    getpwcfg           lookup in dbisPasswdConfig database
    getpwnam           lookup in passwd database
    getpwuid           lookup in passwd database (by uidNumber)
    getrpcbyname       lookup in rpc database
    getrpcbynumber     lookup in rpc database (by rpcNumber)
    getrpccfg          lookup in dbisRpcConfig database
    getservbyname      lookup in services database
    getservbyport      lookup in services database (by ipPortNumber)
    getservcfg         lookup in dbisServiceConfig database
    innetgr            lookup in netgroup database
    innetgr2           lookup in netgroup database
    innetsv            lookup in netservice database

Command-line arguments

dbis accepts the following command-line arguments:

Option	Description
`-D` (`--debug`)	Turn on debug mode.
`-e` (`--recurse`)	Recurse member netgroups. This is used in conjunction with `dbis getnetgrent` and will replace expand any included netgroups to produce a list tuples only.
`-h` (`--help`) `[command]`	Display help message and list all valid subcommands. If a specific command is given, display help on the specified command.
`-l` (`--long`)	Display long output. This will display all of the data contained in the LDAP entry in a format similar to LDIF. The default is to display the data in a format similar to the `getent` command.
`-n` (`--nss`)	Set output format to NSS-style, i.e. similar to the `getent` command. This is the default behaviour.
`-o` (`--sort`)	Sort output. This sorts entries in dictionary order. If displaying long output with the `-l` option, the attributes within a single entry will also be sorted.
`-p` (`--pprint`)	Pretty-print non-string attribute data encountered when rendering long or raw output.
`-s` (`--server`) `address`	Connect to DBIS server on this address. Can be in the format `host:port` or a pathname to a UNIX domain socket. The default is `/var/run/dbis/client`.
`-t` (`--stream`)	Set output format to data stream (binary) mode. This is the output format used by the NSS library over the `/var/run/dbis/nss` socket
`-v` (`--version`)	Display program version and copyright message, then exit.
`-w` (`--width`) `width`	Override terminal width with alternative value. This affects how raw data is pretty-printed when used alongside the `-p` option.

Examples

Displaying a single entry from the passwd map:

$ dbis getpwnam mark
mark:x:801:900:Bannister, Mark:/home/mark:/bin/bash

Displaying a single entry from the passwd map in long output:

$ dbis -l getpwnam mark
          Database: passwd
           Command: getpwnam mark
    Time retrieved: Fri Jan  9 07:35:06 2015

                DN: en=mark,ou=passwd,ou=sales,o=infra
      Last updated: Fri Jan  9 07:28:03 2015 (422.9773 seconds ago)
       objectClass: top
       objectClass: inetOrgPerson
       objectClass: posixUserAccount
                en: mark
       displayName: Bannister, Mark
                cn: Mark
        loginShell: /bin/bash
         uidNumber: 801
         gidNumber: 900
                sn: Bannister
     homeDirectory: /home/mark
      dbisMapGecos: displayName

Displaying a single entry from the passwd map in raw format:

$ dbis -r getpwnam mark
(('en=mark,ou=passwd,ou=sales,o=infra', {'en': ['mark'], 'displayName': ['Bannister, Mark'], 'cn': ['Mark'], 'objectClass': ['top', 'inetOrgPerson', 'posixUserAccount'], 'loginShell': ['/bin/bash'], 'uidNumber': ['801'], 'gidNumber': ['900'], 'sn': ['Bannister'], 'homeDirectory': ['/home/mark'], 'dbisMapGecos': ['displayName']}), 1420788483.685508, 900)

Displaying a single entry from the passwd map in raw format with pretty-print:

$ dbis -rp getpwnam mark
(('en=mark,ou=passwd,ou=sales,o=infra',
  {'cn': ['Mark'],
   'dbisMapGecos': ['displayName'],
   'displayName': ['Bannister, Mark'],
   'en': ['mark'],
   'gidNumber': ['900'],
   'homeDirectory': ['/home/mark'],
   'loginShell': ['/bin/bash'],
   'objectClass': ['top', 'inetOrgPerson', 'posixUserAccount'],
   'sn': ['Bannister'],
   'uidNumber': ['801']}),
 1420788483.685508,
 900)

Iterating all entries in the hosts map:

$ dbis gethostbyname '*'
0:1:2:3:4:5:6:7 picard-hive
10.11.12.13     picard
10.11.12.15     kilcher2
23:0:7:0:1:2:3:4        peg6.aja.com
23.0.7.1        peg.aja.com
10.11.12.14     kilcher