LB_ADMIN(8) Domain/OS BSD LB_ADMIN(8)
NAME
lb_admin - Location Broker Administrative Tool
SYNOPSIS
/etc/ncs/lb_admin [ -nq ] [ -version ]
DESCRIPTION
The lb_admin tool administers the registrations of NCS-based servers in
Global Location Broker (GLB) or Local Location Broker (LLB) databases. A
server registers NCS 1.5.1-style Universal Unique Identifiers (UUIDs)
specifying an object, a type, and an interface, along with a socket
address specifying its location. A client can locate servers by issuing
lookup requests to GLBs and LLBs. Using the lb_admin tool, you can look
up information, add new entries, and delete existing entries in a
specified database.
The lb_admin tool is useful for inspecting the contents of Location
Broker databases and for correcting database errors. For example, if a
server terminates abnormally without unregistering itself, you can use
lb_admin to manually remove its entry from the GLB database.
In accepting input or displaying output, lb_admin uses either character
strings or descriptive textual names to identify objects, types, and
interfaces. A character string directly represents the data in a NCS
1.5.1-style UUID in the format xxxxxxxxxxxx.xx.xx.xx.xx.xx.xx.xx.xx,
where each x is a hexadecimal digit. Descriptive textual names are
associated with UUIDs in the uuidname.txt file. (Note that if an NCS
2.0-based server registers itself in the GLB database and you use
lb_admin to look at the registration, lb_admin will show the wrong string
representation of the UUID.)
With lb_admin, you examine or modify only one database at a time, which
we refer to as the "current database." The use_broker command selects the
type of Location Broker database, GLB or LLB. The set_broker command
selects the host whose GLB or LLB database is to be accessed. Of course,
if you modify one replica of a replicated GLB database, your
modifications will be propagated to the other replicas of that database.
On Domain/OS systems, lb_admin presents both a Domain/Dialogue window-
oriented user interface and a terminal-oriented interface. On other
systems, it presents only the terminal-oriented interface. Here we
describe the terminal-oriented interface to lb_admin. For information on
the Domain/Dialogue interface, use the HELP key or the right mouse
button, or see Managing NCS Software.
OPTIONS
-nq Do not query for verification of wildcard expansions in
unregister operations.
-version Display the version of NCK that this lb_admin belongs to, but
do not start the tool.
COMMANDS
In lookup, register, and unregister commands, the object, type, and
interface arguments can be either character strings representing UUIDs or
textual names corresponding to UUIDs, as described earlier.
a[dd] Synonym for register.
c[lean] Find and delete obsolete entries in the current database. When
you clean a database, you should invoke lb_admin on a host that
is running all the protocols that servers might have used to
register themselves in the database. In most configurations,
this means that you should run lb_admin clean from a Domain/OS
host that is running both the DDS and IP protocols.
When you issue the clean command, lb_admin attempts to contact
each server registered in the database. If the server
responds, the entry for its registration is left intact in the
database. If the server does not respond, lb_admin tries to
look up its registration in the LLB database at the host where
the server is located, tells you the result of this lookup, and
asks whether you want to delete the entry. If a server
responds, but its UUIDs do not match the entry in the database,
lb_admin tells you this result and asks whether you want to
delete the entry.
There are two situations in which it is likely that a database
entry should be deleted:
+ The server does not respond, lb_admin succeeds in contacting
the LLB at the host where the server is located, and the
server is not registered with that LLB. The server is
probably no longer running.
+ A server responds, but its UUIDs do not match the entry in
the database. The server that responded is not the one that
registered the entry.
Entries that meet either of these conditions are probably safe
to delete and are considered eligible for "automatic deletion"
(described in the next paragraph). In other situations, it is
best not to delete the entry unless you can verify directly
that the server is not running (for example, by listing the
processes running on its host).
When lb_admin asks whether you want to delete an entry, you
have four ways to respond. A y[es] response deletes the entry.
A n[o] response leaves the entry intact in the database. After
a yes or a no, lb_admin proceeds to check the next entry in the
current database. A g[o] response invokes automatic deletion,
in which all eligible entries are deleted and all ineligible
entries are left intact, without your being queried, until all
entries have been checked. A q[uit] response terminates the
clean operation.
d[elete] Synonym for unregister.
h[elp] [command] or ? [command]
Display a description of the specified command or, if none is
specified, list all of the lb_admin commands.
l[ookup] object type interface
Look up and display all entries with matching object, type, and
interface fields in the current database. You can use
asterisks as wildcards for any of the arguments. If all the
arguments are wildcards, lookup displays the entire database.
q[uit] Exit the lb_admin session.
r[egister] object type interface location annotation [flag]
Add the specified entry to the current database. You can use
an asterisk to represent the nil UUID in the object, type, and
interface fields.
The location is a string in the format family:host[port], where
family is an address family, host is a host name, and port is a
port number. Possible values for family include dds and ip.
You can use a leading # to indicate that a host name is in the
standard numeric form. For example, dds://salzburg[515],
dds:#575d.542e[452], ip:vienna[1756], and ip:#192.5.5.5[1791]
are all acceptable location specifiers.
The annotation is a string of up to 64 characters annotating
the entry. Use double quotation marks to delimit a string that
contains a space or contains no characters. To embed a double
quotation mark in the string, precede it with a backslash.
The flag is either local (the default) or global, indicating
whether the entry should be marked for local registration only
or for registration in both the LLB and GLB databases. The
flag is a field that is stored with the entry; it does not
affect where the entry is registered. The set_broker and
use_broker commands select the particular LLB or GLB database
for registration.
s[et_broker] [broker_switch] host
Set the host for the current LLB or GLB. If you specify global
as the broker_switch, set_broker sets the current GLB;
otherwise, it sets the current LLB. The host is a string in
the format family:host, where family is an address family and
host is a host name. Possible values for family include dds
and ip. You can use a leading # to indicate that a host name
is in the standard numeric form. For example, dds://linz,
dds:#499d.590f, ip:prague, and ip:#192.5.5.5 are all acceptable
host specifiers.
Issue use_broker, not this command, to determine whether
subsequent operations will access the LLB or the GLB.
set_t[imeout] [short | long]
Set the timeout period used by lb_admin for all of its
operations. With an argument of short or long, set_timeout
sets the timeout accordingly. With no argument, it displays
the current timeout value.
u[nregister] object type interface location
Delete the specified entry from the current database.
The location is a string in the format family:host[port], where
family is an address family, host is a host name, and port is a
port number. Possible values for family include dds and ip.
You can use a leading # to indicate that a host name is in the
standard numeric form. For example, dds://salzburg[515],
dds:#575d.542e[452], ip:vienna[1756], and ip:#192.5.5.5[1791]
are all acceptable location specifiers.
You can use an asterisk as a wildcard in the object, type, and
interface fields to match any value for the field. Unless you
have suppressed queries by invoking lb_admin with the -nq
option, unregister asks you whether to delete each matching
entry. A y[es] response deletes the entry. A n[o] response
leaves the entry in the database. A g[o] response deletes all
remaining database entries that match, without your being
queried. A q[uit] response terminates the unregister
operation, without deleting any more entries.
us[e_broker] [broker_switch]
Select the type of database that subsequent operations will
access, GLB or LLB. The broker_switch is either global or
local. If you do not supply a broker_switch, use_broker tells
whether the current database is global or local.
Use set_broker to select the host whose GLB or LLB is to be
accessed.
SEE ALSO
drm_admin(8), glbd(8), llbd(8), uuidname.txt(5)
Managing NCS Software