NAME

netdb - Create, Modify or Delete NetDB Records

SYNOPSIS

netdb node admin --add admin, ... --remove admin, ... [ --input file | node ... ]

netdb node alias --add alias, ... --remove alias, ... name

netdb node comment [ --set comment | --clear ] [ --input file | node ... ]

netdb node custom --add name[=value], ... --remove name[=value], ... [ --input file | node ... ]

netdb node delete [ --keep_mx ] [ --force ] [ --input file | node ... ]

netdb node department --set department [ --input file | node ... ]

netdb node expiration [ --set date | --clear ] [ --input file | node ... ]

netdb node group --add group, ... --remove group, ... [ --input file | node ... ]

netdb node info [ --json ] [ --input file | node ... ]

netdb node ip_address --remove old_ip [ --add new_ip[+] ] node

netdb node ip_address --set [in]active [ --input file | address ... ]

netdb node ipc_address [ --remove ip, ... ] [ --add ip[+][/count], ... ] node

netdb node location --set [building]:room [ --input file | node ... ]

netdb node log [ --name name ] [ --ip ip ] [ --id record_id ] [ --after date ] [ --before date ] [ --state state ] [ --user netid ]

netdb node model --set make:model [ --input file | node ... ]

netdb node name [ --add new_name ] [ --remove old_name | --ip IP address | --interface (hardware address | IP address) ] node

netdb node os --add os, ... --remove os, ... [ --input file | node ... ]

netdb node ptr_pref --set closest | all [ --input file | address ... ]

netdb node receive_mail_for --add mailname[:preference], ... --remove mailname, ... name

netdb node search [ --input file | node ... ]

netdb node state --set state [ --input file | node ... ]

netdb node user --add user, ... --remove user, ... [ --input file | node ... ]

- or -

netdb node clone --template node --name name [ --location building:room | :room ] [ --hardware|hw hardware address [ --dhcp ] [ --roam ] ] [ --ip ip address[+] | none ] [ --model make:model ] [ --os os, ... ] [ --user user, ... ] [ --admin admin, ... ] [ --custom all | names | none ] [ --comment comment ] [ --type type, ... ]

- or -

netdb node interface --add hardware address [ --dhcp[=(on|off)] ] [ --options option=value,... ] [ --roam ] [ --ip ip address[+] [ --ptr_pref (closest | all) ] ] [ --comment comment ] [ --name name ] node

netdb node interface --add none --ip ip address[+] [ --ptr_pref (closest | all) ] [ --comment comment ] [ --name name ] node

netdb node interface --modify (hardware address | IP address) [ --hardware|hw hardware address | none ] [ --dhcp[=(on|off)] ] [ --options option=value,... ] [ --roam[=(on|off)] ] [ --ip ip address[+] [ --ptr_pref (closest | all) ] ] [ --comment comment ] [ --name name ] node

netdb node interface --move (hardware address | IP address)[=new_hardware_address],... --destination dest_node node

netdb node interface --remove (hardware address | IP address), ... node

- or -

netdb user active_flag [ --set | --clear ] [ --input file | netid ... ]

netdb user all_groups_flag [ --set | --clear ] [ --input file | netid ... ]

netdb user all_records_flag [ --set | --clear ] [ --input file | netid ... ]

netdb user comment [ --set comment | --clear ] [ --input file | netid ... ]

netdb user default_domain --set domain [ --input file | netid ... ]

netdb user default_group --set group [ --input file | netid ... ]

netdb user delete [ --input file | netid ... ]

netdb user department --add department;... --remove department;... [ --input file | netid ... ]

netdb user group --add group,... --remove group,... [ --input file | netid ... ]

netdb user info [ --json ] [ --input file | netid ... ]

netdb user oauthid [ --set oauthid | --clear ] [ --input file | netid ... ]

netdb user record --add record,... --remove record,... [ --input file | netid ... ]

netdb user search [ --input file | netid ... ]

netdb user starting_address [ --set address | --clear ] [ --input file | netid ... ]

- or -

netdb user clone --template netid [ --comment comment ] [ --oauthid id ] [ --input file | netid ... ]

netdb user create --domain domain --def[ault]_group group [ --department department;... ] [ --group group,... ] [ --[in]active ] [ --all_groups ] [ --all_records ] [ --record record,... ] [ --starting_address address ] [ --comment comment ] [ --oauthid id ] [ --input file | netid ... ]

- or -

netdb list [ --json ] [ departments | locations | models | oses | vlan_areas ] [ regexp ]

netdb list [ --json ] [ node_types | states ] [ all ]

netdb list [ --json ] groups [ all | regexp | all regexp ]

netdb list [ --json ] dhcp_options [ interface | address_space | network | dhcp_service ]

netdb list service

- or -

netdb [ domain | network | txt_record ] help

- or -

netdb --batch [ command_file | - ]

- or -

netdb --keytab keytab --principal principal (node | user | list) ...

netdb --keytab keytab --principal principal --batch [ command_file | - ]

- or -

netdb --help

netdb --usage

netdb --version

- to suppress informational warning messages -

netdb --quiet

DESCRIPTION

netdb is a utility for creating, modifying, and deleting NetDB records. Its first argument is the record type, e.g., node or network, or list, which lists valid values of various attributes. Its second argument is a keyword - clone, delete, log, search, or the name of an attribute to be modified or listed. Keywords are followed by keyword-specific options and arguments. Keywords and options need not be spelled out completely - providing enough characters to uniquely identify a keyword or option is sufficient.

Records may be specified as arguments or read from a file, one per line, using the --input option. Any name, alias, IP or hardware address will work to identify a node record. Your default domain will be appended to unqualified node names. Users should be specified by NetID. If more than one record is given, netdb processes each in the order listed. If there is a problem deleting or modifying a particular record, netdb reports the error and continues to the next record.

The clone keyword creates a new record using an existing record as a template. The names of the existing and new records must be supplied; other record attributes are taken from the template. Options are available to override many of the template attribute values.

The list keyword lists the valid values of the given attribute for the current user. Adding all lists all the values of the attribute. Include the optional regexp parameter to limit the listing to values that match the regular expression. The list keyword can also be used to show the status of the RMI service.

The log keyword searches the log for that record type using the parameters provided in the options. Log search options support wildcards, Boolean operators, and regular expressions.

The search keyword finds nodes by name or IP address, and users by name or NetID. It supports wildcards and IP address ranges expressed with a dash (e.g. 171.64.32.17-21) or as a prefix (e.g., 171.64.32.0/29).

Multiple commands can be run using the --batch option. This can be a real time-saver when running a lot of commands as the time to start netdb is non-trivial.

netdb uses your valid Kerberos ticket to authenticate you to the NetDB server. Or you can use the --keytab and --principal options to authenticate using a Kerberos keytab file. If you don't have a valid ticket, or specify an invalid keytab or principal, netdb exits with an error.

RECORD TYPES

netdb works with node, user, network, domain, and txt_record NetDB records. The remainder of this help deals with the most popular records - node and user. Use the keyword help to get a brief usage summary for each of the other record types, e.g., netdb domain help.

NODE KEYWORDS

admin

Add and/or remove node administrators. Administrators can be specified by NetID or Admin Team Name. To identify the input as an admin team, append a colon (e.g. myteam:).

alias

Add and/or remove aliases of a node name.

clone

Create a new record using an existing record as a template.

comment

Set or clear the comment of a record or records.

custom

Add and/or remove node custom fields. Custom fields are specified as name=value with the value being optional.

delete

Delete a record or records. When deleting node records, mail exchanger entries on other nodes will also be removed unless the --keep_mx option is supplied. Deleting nodes of type router or those having more than 10 aliases and/or mail names requires confirmation unless the --force option is used.

department

Change the department associated with a node or nodes.

expiration

Set or clear the expiration date of a node or nodes. Specify dates in the mm/dd/yyyy form.

group

Add and/or remove record groups.

info

List information about a node or nodes.

interface

Add, modify, move, or remove node interfaces. Interfaces are identified by their hardware or IP addresses.

ip_address

Change or remove a node IP address with the --remove option. The old IP address is required. The operation will fail if node does not have old_ip or new_ip is not available. If a plus is appended to the new IP address, new_ip+, netdb searches for available IP addresses starting at the specified IP address. Use the interface keyword to add an IP address to a node.

Set node interface IP addresses active or inactive with the --set option. A node name is not required, only the IP address(es) to change.

ipc_address

Add or remove IP Connectivity Provider IP addresses. Adds new IP addresses starting with the specified IP address. The operation will fail if the specified IP address is not available. If a plus is appended to the new IP address, ip+, netdb searches for available IP addresses starting at the specified IP address. If count is specified, netdb attempts to add that many addresses. Addresses are added as available and aren't necessarily contiguous.

location

Change the location of a node or nodes. The location is specified as building:room. building is optional and if it's not specified only room is changed.

log

Search the NetDB log for node entries matching the conditions given in the options. Log search options support wildcards, Boolean operators, and regular expressions.

model

Change the make and model of a node or nodes. The new make and model are specified as make:model.

name

Add, remove, or replace a name. If only --add is specified the new name is added as a node name. If --ip or --interface is specified the new name is added to that IP address or interface. If both --add and --remove are specified the new name replaces the old name, be it a node name, interface name, interface IP address name, or IPC IP address name. If only --remove is specified the old name is removed from wherever it occurs on the node. The operation will fail if the new name is not available or the old name is not associated with the node. The Advanced Node privilege is required to make changes to nodes with more than one name.

os

Add and/or remove OSes running on a node or nodes.

ptr_pref

Set the PTR preference for an interface IP address. The PTR preference controls what the DNS returns for reverse lookups of the IP address. If set to all, then all existing IP address, Interface, and Node names will be returned in no particular order. If set to closest, then the first existing IP address name, Interface name, or Node name will be returned.

receive_mail_for

Add and/or remove mail destination names to a node name. A mail exchanger (MX) preference value can be specified in the form mailname:preference. If no MX preference is supplied, a default value of 10 will be assigned.

Find nodes by name or IP address. This keyword supports wildcards in names and IP addresses, as well as IP address ranges expressed with a dash (e.g. 171.64.32.17-21) or as a prefix (e.g., 171.64.32.0/29).

state

Change the state of a node or nodes.

user

Add and/or remove users of a node or nodes. Users are specified by NetID.

USER KEYWORDS

active_flag

Set or clear the active flag for a user or users.

all_groups_flag

Set or clear the all-groups flag, which allows a user to create, modify, or delete records regardless of group membership.

all_records_flag

Set or clear the all-records flag, which allows a user to create, modify, or delete records of any type.

clone

Create a new user or users using an existing user as a template. The template user's comment field will not be carried over to the new records, but a new comment may be provided.

comment

Set or clear the comment for a user or users.

create

Create a new user or users with the specified attributes.

default_domain

Set or clear the default domain for a user or users.

default_group

Set or clear the default group for a user or users.

delete

Delete a user or users.

department

Change the departments with which a user or users are officially affiliated as Local Network Administrators.

group

Change the record groups to which a user or users have access. Users cannot create, modify, or delete records in groups they are not members of (unless they have all-groups access).

info

List information about a user or users.

oauthid

Set or clear the OAuth ID for a user or users.

record

Change the types of records that a user or users can create, modify or delete.

search

Find users by name or NetID. This keyword supports wildcards, e.g. corn*.stanford.edu.

starting_address

Set or clear the starting address for a user or users.

OPTIONS

Modify Options

--add values

Add the specified values to the record or records. Values are input as a comma- or semicolon-separated list of strings, as specified for the particular keyword. To add a value containing the delimiter, escape it with a backslash (\); to add a value containing a backslash, escape the backslash with another backslash. For example, --add 'foo,bar\,baz,C:\\qux' adds the values foo and bar,baz and C:\qux.

--remove values

Remove the specified values from the record or records. Values are input as a comma- or semicolon-separated list of strings, as specified for the particular keyword. To remove a value containing the delimiter, escape it with a backslash (\); to remove a value containing a backslash, escape the backslash with another backslash.

--set value

Set the value of a single-valued attribute.

--clear

Clear the value of an optional single-valued attribute.

--input file

Read the names of the records to create or modify from file, one per line. If file is ``-'', names are read from standard input. Your default domain will be appended to unqualified names.

Clone Options

--template name

The name of an existing record used as a model for the new record.

--comment comment

Use the supplied comment for the new record.

Node Clone Options

--name name

The name of the new record.

--location building:room | :room

Override the template location with this location. To override just the room specify the location as :room.

--hardware|hw hardware address

The hardware address of the new node. Most common hardware address forms (e.g., 0800.2085.8b0f, 08:0:20:85:8b:f, or 08-00-20-85-8b-0f) are accepted.

--dhcp

Set the DHCP flag for the new node (hardware address required).

--roam

Set the DHCP and roaming flags for the new node (hardware address required).

--ip ip address[+] | none

Override the default IP address assignment. If ip address is specified, netdb creates the new node with exactly that IP address. If that IP address is not available, node creation fails. If a plus is appended, ip address+, netdb searches for available IP addresses starting at the specified IP address. The value none means do not assign an IP address to the new node. A hardware address is required if no IP address is requested.

--model make:model

Override the template make and model with this make and model.

--os os, ...

Override the template OSes with these OSes.

--type type, ...

Override the template types with these types.

--user user, ...

Override the template user field with these users. Users are specified by NetID.

--admin admin, ...

Override the template administrator field with these administrators. Administrators can be specified by NetID or Admin Team Name. To identify the input as an admin team, append a colon (e.g. myteam:).

--custom all | names | none

Specifies the parts of the template custom fields to keep. all means keep both names and values; names means keep the names and clear the values; none means don't keep any template custom fields. If this option is not specified the custom field names are preserved and the values are cleared, just as if names was specified.

Interface Options

--add (hardware address | none)

The hardware address of the interface to add. Most common hardware address forms (e.g., 0800.2085.8b0f, 08:0:20:85:8b:f, or 08-00-20-85-8b-0f) are accepted.

To add an interface without a hardware address use the value none. In this case the the --ip option is required since an interface must have at least a hardware address or an IP address.

--modify (hardware address | IP address)

The hardware or IP address of an interface to modify. See --add for valid hardware address forms.

--move (hardware address | IP address)[=new_hardware_address],...

Move the interface(s) with the specified hardware or IP address(es) to the node specified by the --destination argument.

--destination dest_node

Specifies the target node for the --move option.

--remove (hardware address | IP address), ...

The hardware or IP address(es) of interfaces to be removed. See --add for valid hardware address forms.

--hardware|hw hardware address | none

Change or remove the interface hardware address. See --add for valid hardware address forms. Use the value none to remove an existing hardware address.

--dhcp[=(on|off)]

Set or clear the DHCP flag for the interface. If neither on nor off is specified, the flag is set. The default state of the DHCP flag when adding an interface with a hardware address is on.

--roam[=(on|off)]

Set or clear the DHCP roaming flag for the interface. If neither on nor off is specified, the flag is set. The default state of the roaming flag when adding an interface is off. The roaming flag is automatically set off when the DHCP flag is off.

--options option=value,...

Add the specified DHCP options to the interface. To remove an option omit the value: --options option=. To remove all the options specify a blank string: --options "". To replace all the options with new ones start with a blank option: --options "",option=value,....

To add a value containing a comma, escape the comma with a backslash (\). For example, --options 'ntp-servers=fred\,barny'. To add a value containing a backslash, escape the backslash with another backslash. For example, --options 'filename=C:\\foo' adds the option filename=C:\foo.

--ip ip address[+]

Add ip address to the interface. If the IP address is not available, the interface modification fails. If a plus is appended to the IP address, ip address+, netdb searches for available IP addresses starting at the specified IP address.

--ptr_pref closest | all

Set the PTR preference for the new interface IP address. The PTR preference controls what the DNS returns for reverse lookups of the IP address. If set to all, then all existing IP address, Interface, and Node names will be returned in no particular order. If set to closest, then the first existing IP address name, Interface name, or Node name will be returned.

--comment comment

Set the interface comment. Use a blank string to clear the interface comment.

--name name

Set the name of the interface.

User Clone Option

--oauthid ID

Specify the OAuth ID mapping to the new user account.

User Create Options

--domain domain

Specify the default domain for the new user.

--def[ault]_group group

Specify the default group for the new user.

--group group,...

Specify other groups to which the new user should have access.

--department department;...

Specify the departments with which the new user is to be affiliated, in an official LNA capacity.

--[in]active

Specify whether the new user's account should be active or inactive upon creation.

--all_groups

Grant the new user all-groups access. By default, users are created without all-groups access.

--all_records

Grant the new user all-records access. By default, users are created without all-records access.

--oauthid ID

Specify the OAuth ID mapping to the new user account.

--record record,...

Specify the record types to which the new user should have access.

--starting_address address

Specify a starting address for the new user.

Log Options

--name name

Show log entries matching name. If no domain is entered, all domains are searched. The record name must be the actual name - not an alias, interface name, or address name.

--ip ip

Show log entries with IP addresses matching ip. NetDB logs the IP addresses associated with a record after an action has occurred. This means that deleted IP addresses are not logged as part of the delete log entry. To see why an IP has disappeared from NetDB perform a record ID search using the record ID of the last node with the IP address. Note that IPC addresses are not logged for Nodes, nor are Dynamic DHCP addresses logged for Networks.

--id record id

Show log entries for the record with the ID record id. The record ID stays with a particular record, even if it is renamed, until it is deleted.

--after date

Show log entries after date.

--before date

Show log entries before date.

--state state

Show log entries of nodes with the state value state.

--user NetID

Show log entries where NetDB user NetID created/updated/modified the record.

Batch Option

--batch [ command_file | - ]

Take commands from the specified command_file or, when - is specified, the terminal.

The command format is the same as on the command line, starting with a record type followed by a keyword and the appropriate options. Commands may span multiple lines using a backslash (\) to signify that a command continues on the next line. Comments are allowed and delimited by the pound sign (#). Blank lines are ignored.

When taking commands from the terminal netdb prompts with netdb> and supports command recall and editing. If the readline-history-restore gem is installed the command history is preserved between sessions in ~/.netdb_history or the file given by the NETDB_HISTORY environmental variable.

Batch mode includes a ``sleep seconds'' directive that can be used to create a delay between commands. It takes a number, integer or float, as the argument and sleeps for that many seconds.

Authentication Options

--keytab keytab

Path to a Kerberos keytab file to be used for authentication.

--principal principal

Authenticate as this Kerberos principal using the specified keytab.

Other Options

--help

Print a detailed description of how to use netdb.

--usage

Print a short description of how to use netdb.

--version

Print netdb version information.

--json=(compact|pretty)]

When used with the info keyword, returns the results in JSON format, keyed by the arguments. Unmatched arguments are included with an { "error": "reason" } JSON structure.

When used with the list keyword, returns a JSON array of values.

JSON output is pretty printed by default. Use the optional value compact to get the compact version instead.

--service RMI service

Use the specified RMI service instead of the default RMI service. Services can be specified by service name or a server:port combination.

--quiet

Suppress informational warning messages, for example messages that say an attribute to be added to an entry is already part of that entry.

EXAMPLES

Move nodes listed in file moved to Sugar Hall, room A3.
 netdb node location --set "Sugar Hall:A3" --input moved

   - or -

 netdb node loc --s "Sugar Hall:A3" --in moved
Delete node diamond
 netdb node delete diamond

   - or -

 netdb node del diamond
Create node chip based on node oldblock
  netdb node clone --template oldblock --name chip \
                   --hw aa:00:04:64:a7:08 --dhcp
Create a user stevie with the same access and affiliations as ray
 netdb user clone --template ray stevie
Grant all-groups access to the user nina
 netdb user all_groups_flag --set nina

   - or -

 netdb user all_g --s nina
List locations with names beginning with ``main''.
 netdb list location 'main*'

   - or -

 netdb list loc 'main*'

CAVEATS

Any SUNetID (e.g., John.Doe, or j.doe, or jdoe) will usually work for adding node users or administrators, but only the Kerberos SUNetID (e.g., jdoe) works for removing them. The same is true for creating, modifying, and deleting NetDB user records. This is because NetDB doesn't store all the SUNetIDs, only the Kerberos SUNetID.

The UNIX command interpreter, the shell, breaks commands up on spaces. Elements of a command that contain spaces must be quoted for the shell to treat them as a single entity. So when entering netdb commands that have elements containing spaces, comment or location for example, be sure to enclose those elements in quotes.

netdb allows you to quickly change any number of NetDB records. If you're not careful, you can screw them up just as fast.

SEE ALSO

NetDB online help (http://web.stanford.edu/group/networking/netdb/help/prod/index.html)