diff --git a/usr.sbin/boot0cfg/boot0cfg.8 b/usr.sbin/boot0cfg/boot0cfg.8 index f3c942bf27f7..4d622a261357 100644 --- a/usr.sbin/boot0cfg/boot0cfg.8 +++ b/usr.sbin/boot0cfg/boot0cfg.8 @@ -1,206 +1,205 @@ .\" Copyright (c) 1999 Robert Nordier .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, .\" OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT .\" OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR .\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, .\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE .\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 4, 2012 .Dt BOOT0CFG 8 .Os .Sh NAME .Nm boot0cfg .Nd boot manager installation/configuration utility .Sh SYNOPSIS .Nm .Op Fl Bv .Op Fl b Ar boot0 .Op Fl d Ar drive .Op Fl e Ar bell character .Op Fl f Ar file .Op Fl i Ar volume-id .Op Fl m Ar mask .Op Fl o Ar options .Op Fl s Ar slice .Op Fl t Ar ticks .Ar disk .Sh DESCRIPTION The .Fx .Sq boot0 boot manager permits the operator to select from which disk and slice an i386 machine (PC) is booted. .Pp Note that what are referred to here as .Dq slices are typically called .Dq partitions in .No non- Ns Bx documentation relating to the PC. Typically, only non-removable disks are sliced. .Pp The .Nm utility optionally installs the .Sq boot0 boot manager on the specified .Ar disk ; and allows various operational parameters to be configured. .Pp On PCs, a boot manager typically occupies sector 0 of a disk, which is known as the Master Boot Record (MBR). The MBR contains both code (to which control is passed by the PC BIOS) and data (an embedded table of defined slices). .Pp The options are: .Bl -tag -width indent .It Fl B Install the .Sq boot0 boot manager. This option causes MBR code to be replaced, without affecting the embedded slice table. .It Fl b Ar boot0 Specify which .Sq boot0 image to use. The default is .Pa /boot/boot0 which will use the video card as output, alternatively .Pa /boot/boot0sio can be used for output to the COM1 port. (Be aware that nothing will be output to the COM1 port unless the modem signals DSR and CTS are active.) .It Fl d Ar drive Specify the drive number used by the PC BIOS in referencing the drive which contains the specified .Ar disk . Typically this will be 0x80 for the first hard drive, 0x81 for the second hard drive, and so on; however any integer between 0 and 0xff is acceptable here. .It Fl e Ar bell character Set the character to be printed in case of input error. .It Fl f Ar file Specify that a backup copy of the preexisting MBR should be written to .Ar file . This file is created if it does not exist, and replaced if it does. .It Fl i Ar volume-id Specifies a volume-id (in the form XXXX-XXXX) to be saved at location 0x1b8 in the MBR. This information is sometimes used by NT, XP and Vista to identify the disk drive. The option is only compatible with version 2.00 of the 512-byte boot block. .It Fl m Ar mask Specify slices to be enabled/disabled, where .Ar mask is an integer between 0 (no slices enabled) and 0xf (all four slices enabled). Each mask bit enables corresponding slice if set to 1. The least significant bit of the mask corresponds to slice 1, the most significant bit of the mask corresponds to slice 4. .It Fl o Ar options A comma-separated string of any of the following options may be specified (with .Dq no prepended as necessary): .Bl -tag -width indent .It packet Use the disk packet (BIOS INT 0x13 extensions) interface, as opposed to the legacy (CHS) interface, when doing disk I/O. This allows booting above cylinder 1023, but requires specific BIOS support. The default is .Sq packet . .It setdrv Forces the drive containing the disk to be referenced using drive number definable by means of the -d option. The default is .Sq nosetdrv . .It update Allow the MBR to be updated by the boot manager. (The MBR may be updated to flag slices as .Sq active , and to save slice selection information.) This is the default; a .Sq noupdate option causes the MBR to be treated as read-only. .El .It Fl s Ar slice Set the default boot selection to .Ar slice . Values between 1 and 4 refer to slices; a value of 5 refers to the option of booting from a second disk. The special string .Dq PXE or a value of 6 can be used to boot via PXE. .It Fl t Ar ticks Set the timeout value to .Ar ticks . (There are approximately 18.2 ticks per second.) .It Fl v Verbose: display information about the slices defined, etc. .El .Sh FILES .Bl -tag -width /boot/boot0sio -compact .It Pa /boot/boot0 The default .Sq boot0 image .It Pa /boot/boot0sio Image for serial consoles (COM1,9600,8,N,1,MODEM) .El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES To boot slice 2 on the next boot: .Pp .Dl "boot0cfg -s 2 ad0" .Pp To enable just slices 1 and 3 in the menu: .Pp .Dl "boot0cfg -m 0x5 ad0" .Pp To go back to non-interactive booting, use .Xr fdisk 8 to install the default MBR: .Pp .Dl "fdisk -B ad0" -.Pp .Sh SEE ALSO .Xr geom 4 , .Xr boot 8 , .Xr fdisk 8 , .Xr gpart 8 .Sh AUTHORS .An Robert Nordier Aq rnordier@FreeBSD.org . .Sh BUGS Use of the .Sq packet option may cause .Sq boot0 to fail, depending on the nature of BIOS support. .Pp Use of the .Sq setdrv option with an incorrect -d operand may cause the boot0 code to write the MBR to the wrong disk, thus trashing its previous content. Be careful. diff --git a/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 b/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 index ceab05126a1e..23a8bfe67b66 100644 --- a/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 +++ b/usr.sbin/bsnmpd/modules/snmp_netgraph/snmp_netgraph.3 @@ -1,436 +1,435 @@ .\" .\" Copyright (c) 2001-2003 .\" Fraunhofer Institute for Open Communication Systems (FhG Fokus). .\" All rights reserved. .\" .\" Author: Harti Brandt .\" .\" Redistribution of this software and documentation and use in source and .\" binary forms, with or without modification, are permitted provided that .\" the following conditions are met: .\" .\" 1. Redistributions of source code or documentation must retain the above .\" copyright notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE AND DOCUMENTATION IS PROVIDED BY FRAUNHOFER FOKUS .\" AND ITS CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, .\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND .\" FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL .\" FRAUNHOFER FOKUS OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT .\" LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, .\" OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF .\" LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING .\" NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, .\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd November 14, 2003 .Dt SNMP_NETGRAPH 3 .Os .Sh NAME .Nm snmp_netgraph , .Nm snmp_node , .Nm snmp_nodename , .Nm ng_cookie_f , .Nm ng_hook_f , .Nm ng_register_cookie , .Nm ng_unregister_cookie , .Nm ng_register_hook , .Nm ng_unregister_hook , .Nm ng_unregister_module , .Nm ng_output , .Nm ng_output_node , .Nm ng_output_id , .Nm ng_dialog , .Nm ng_dialog_node , .Nm ng_dialog_id , .Nm ng_send_data , .Nm ng_mkpeer_id , .Nm ng_connect_node , .Nm ng_connect_id , .Nm ng_connect2_id , .Nm ng_connect2_tee_id , .Nm ng_rmhook , .Nm ng_rmhook_id , .Nm ng_rmhook_tee_id , .Nm ng_shutdown_id , .Nm ng_next_node_id , .Nm ng_node_id , .Nm ng_node_id_node , .Nm ng_node_name , .Nm ng_node_type , .Nm ng_peer_hook_id .Nd "netgraph module for snmpd. .Sh LIBRARY .Pq begemotSnmpdModulePath."netgraph" = "/usr/lib/snmp_netgraph.so" .Sh SYNOPSIS .In bsnmp/snmpmod.h .In bsnmp/snmp_netgraph.h .Vt extern ng_ID_t snmp_node ; .Vt extern u_char *snmp_nodename ; .Ft typedef void .Fn ng_cookie_f "const struct ng_mesg *mesg" "const char *path" "ng_ID_t id" "void *uarg" .Ft typedef void .Fn ng_hook_f "const char *hook" "const u_char *mesg" "size_t len" "void *uarg" .Ft void * .Fn ng_register_cookie "const struct lmodule *mod" "uint32_t cookie" "ng_ID_t id" "ng_cookie_f *func" "void *uarg" .Ft void .Fn ng_unregister_cookie "void *reg" .Ft void * .Fn ng_register_hook "const struct lmodule *mod" "const char *hook" "ng_hook_f *func" "void *uarg" .Ft void .Fn ng_unregister_hook "void *reg" .Ft void .Fn ng_unregister_module "const struct lmodule *mod" .Ft int .Fn ng_output "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft int .Fn ng_output_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft int .Fn ng_output_id "ng_ID_t node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft struct ng_mesg * .Fn ng_dialog "const char *path" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft struct ng_mesg * .Fn ng_dialog_node "const char *node" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft struct ng_mesg * .Fn ng_dialog_id "ng_ID_t id" "u_int cookie" "u_int opcode" "const void *arg" "size_t arglen" .Ft int .Fn ng_send_data "const char *hook" "const void *sndbuf" "size_t sndlen" .Ft ng_ID_t .Fn ng_mkpeer_id "ng_ID_t id" "const char *name" "const char *type" "const char *hook" "const char *peerhook" .Ft int .Fn ng_connect_node "const char *node" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_connect_id "ng_ID_t id" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_connect2_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_connect2_tee_id "ng_ID_t id" "ng_ID_t peer" "const char *ourhook" "const char *peerhook" .Ft int .Fn ng_rmhook "const char *ourhook" .Ft int .Fn ng_rmhook_id "ng_ID_t id" "const char *hook" .Ft int .Fn ng_rmhook_tee_id "ng_ID_t id" "const char *hook" .Ft int .Fn ng_shutdown_id "ng_ID_t id" .Ft ng_ID_t .Fn ng_next_node_id "ng_ID_t node" "const char *type" "const char *hook" .Ft ng_ID_t .Fn ng_node_id "const char *path" .Ft ng_ID_t .Fn ng_node_id_node "const char *node" .Ft ng_ID_t .Fn ng_node_name "ng_ID_t id" "char *name" .Ft ng_ID_t .Fn ng_node_type "ng_ID_t id" "char *type" .Ft int .Fn ng_peer_hook_id "ng_ID_t id" "const char *hook" "char *peerhook" .Sh DESCRIPTION The .Nm snmp_netgraph module implements a number of tables and scalars that enable remote access to the netgraph subsystem. It also exports a number of global variables and functions, that allow other modules to easily use the netgraph system. .Pp If upon start up of the module the variable .Va begemotNgControlNodeName is not empty the module opens a netgraph socket and names that socket node. If the variable is empty, the socket is created, as soon as the variable is written with a non-empty name. The socket can be closed by writing an empty string to the variable. The socket itself and its name are available in .Va snmp_node and .Va snmp_nodename . .Ss SENDING AND RECEIVING MESSAGES AND DATA There are three functions for sending control message: .Bl -tag -width ".It Fn ng_output_node" .It Fn ng_output sends a control message along the given .Fa path . .It Fn ng_output_node sends a control message to the node with name .Fa node and .It Fn ng_output_id sends a control message to the node with node id .Fa id . .El .Pp Each of these functions takes the following arguments: .Bl -tag -width ".It Fa cookie" .It Fa cookie is the node specific command cookie, .It Fa opcode is the node specific code for the operation to perform, .It Fa arg is a pointer to the message itself. This message must start with a .Vt struct ng_mesg . .It Fa arglen is the overall length of the message (header plus arguments). .El The functions return the message id that can be used to match incoming responses or -1 if an error occurs. .Pp Another class of functions is used to send a control message and to wait for a matching response. Note, that this operation blocks the daemon, so use it only if you are sure that the response will happen. There is a maximum timeout that is configurable in the MIB variable .Va begemotNgTimeout . Other messages arriving while the functions are waiting for the response are queued and delivered on the next call to the module's idle function. .Bl -tag -width ".It Fn ng_output_node" .It Fn ng_dialog sends a control message along the given .Fa path and waits for a matching response. .It Fn ng_dialog_node sends a control message to the node with name .Fa node and waits for a matching response. .It Fn ng_dialog_id sends a control message to the node with id .Fa id and waits for a matching response. .El .Pp All three functions take the same arguments as the .Fn ng_output* functions. The functions return the response message in a buffer allocated by .Xr malloc 3 or NULL in case of an error. The maximum size of the response buffer can be configured in the variable .Va begemotNgResBufSiz . .Pp A data message can be send with the function .Fn ng_send_data . This function takes the name of the .Va snmp_node Ns 's hook through which to send the data, a pointer to the message buffer and the size of the message. It returns -1 if an error happens. .Ss ASYNCHRONOUS CONTROL AND DATA MESSAGES A module can register functions to asynchronously receive control and data message. .Pp The function .Fn ng_register_cookie registers a control message receive function. If a control message is received, that is not consumed by the dialog functions, the list of registered control message receive functions is scanned. If the cookie in the received message is the same as the .Fa cookie argument to the .Fn ng_register_cookie call and the .Fa id argument to the .Fn ng_register_cookie call was either 0 or equals the node id which sent the control message, the handler function .Fa func is called with a pointer to the received message, the hook on which the message was received (or NULL if it was received not on a hook), the id of the sender's node and the .Fa uarg argument of the registration call. The handler function should not modify the contents of the message, because more than one function may be registered to the same cookie and node id. .Pp A control message registration can be undone by calling .Fn ng_unregister_cookie with the return value of the registration call. If an error occurs while registering, .Fn ng_register_cookie returns NULL. .Pp A module can call .Fn ng_register_hook to register a callback for data messages on one of the .Va snmp_node Ns 's hooks. If a data message is received on that hook, the callback function .Fa func is called with the hook name, a pointer to the data message, the size of the message and the argument .Fa uarg to the registration function. The message should be treated as read-only. A data message registration can be undone by calling .Fn ng_unregister_hook with the return value of the registration call. If an error occurs while registering, .Fn ng_register_hook returns NULL. .Pp The function .Fn ng_unregister_module removes all control and data registrations for that module. .Ss FINDING NODES AND NODE CHARACTERISTICS -.Pp The function .Fn ng_node_id returns the id of the node addressed by .Fa path or 0 if the node does not exists. .Pp The function .Fn ng_node_id_node returns the id of the node with name .Fa node or 0 if the node does not exist. .Pp The function .Fn ng_node_node retrieves the name of the node with id .Fa id and writes it to the buffer pointed to by .Fa name . This buffer should be at least .Li NG_NODESIZ bytes long. The function returns the node id or 0 if the node is not found .Pp The function .Fn ng_node_type retrieves the name of the node with id .Fa id and writes it to the buffer pointed to by .Fa type . This buffer should be at least .Li NG_TYPESIZ bytes long. The function returns the node id or 0 if the node is not found. .Pp The function .Fn ng_peer_hook_id writes the name of the peer hook of the hook .Fa hook on the node with .Fa id to the buffer pointed to by .Fa peer_hook . The buffer should be at least .Li NG_HOOKSIZ bytes long. The function returns 0 if the node and the hook is found, -1 otherwise. The function skips intermediate tee nodes (see .Xr ng_tee 4 ) . .Pp The function .Fn ng_next_node_id returns the node id of the peer node that is on the other side of hook .Fa hook of node .Fa id . If .Fa type is not NULL, the function checks, that the peer node's type is .Fa type . The function skips intermediate tee nodes (see .Xr ng_tee 4 ) . It returns the node id of the peer node or 0 if an error occurs or the types do not match. .Ss CHANGING THE GRAPH A number of functions can be used to create or destroy nodes and hooks. .Pp The function .Fn ng_mkpeer_id creates a new node of type .Fa type whose hook .Fa peerhook will be connected to .Fa hook of node .Fa id . If .Fa name is not NULL the new node is named with this name. The function returns The node id of the new node or 0 if an error happens. .Pp The functions .Fn ng_connect_node and .Fn ng_connect_id make a new hook connecting .Fa ourhook of the modules socket node .Va snmp_node to .Fa peerhook of the node identified by id .Fa id or name .Fa node . The functions return 0 on success or -1 otherwise. .Pp The function .Fn ng_connect2_id connects hook .Fa ourhook of the node with id .Fa id to hook .Fa peerhook of the node with id .Fa peer . The functions return 0 on success or -1 otherwise. The function .Fn ng_connect2_tee_id does the same as .Fn ng_connect2_id except, that it puts an unnamed tee node between the two nodes. .Pp The function .Fn ng_rmhook removes hook .Fa hook on the module's .Va snmp_node . The function .Fn ng_rmhook_id removes hook .Fa hook on the node with id .Fa id . The function .Fn ng_rmhook_tee_id additionally shuts down all tee nodes between the node and the first non-tee peer. .Pp The function .Fn ng_shutdown_id destroys the given node. .Sh FILES .Bl -tag -width "XXXXXXXXX" .It Pa /usr/share/bsnmp/defs/netgraph_tree.def The description of the MIB tree implemented by .Nm . .It Pa /usr/share/bsnmp/mibs/BEGEMOT-NETGRAPH.txt This is the MIB that is implemented by this module. .El .Sh SEE ALSO .Xr gensnmptree 1 , .Xr snmpmod 3 .Sh AUTHORS .An Hartmut Brandt Aq harti@FreeBSD.org diff --git a/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 b/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 index 950c114f79ab..23cf943cc31e 100644 --- a/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 +++ b/usr.sbin/bsnmpd/tools/bsnmptools/bsnmpget.1 @@ -1,427 +1,426 @@ .\" .\" Copyright (c) 2010 The FreeBSD Foundation .\" All rights reserved. .\" .\" Portions of this documentation were written by Shteryana Sotirova Shopova .\" under sponsorship from the FreeBSD Foundation. .\" .\" Copyright (c) 2005-2007 The FreeBSD Project. .\" All rights reserved. .\" .\" Author: Shteryana Shopova .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd January 10, 2012 .Dt BSNMPGET 1 .Os .Sh NAME .Nm bsnmpget , .Nm bsnmpwalk , .Nm bsnmpset .Nd "simple tools for querying SNMP agents" .Sh SYNOPSIS .Nm .Op Fl aDdehnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl M Ar max-repetitions .Op Fl N Ar non-repeaters .Op Fl o Ar output .Op Fl P Ar options .Op Fl p Ar pdu .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Op Ar OID ... .Pp .Nm bsnmpwalk .Op Fl dhnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl o Ar output .Op Fl P Ar options .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Op Ar OID ... .Pp .Nm bsnmpset .Op Fl adehnK .Op Fl A Ar options .Op Fl b Ar buffersize .Op Fl C Ar options .Op Fl I Ar options .Op Fl i Ar filelist .Op Fl l Ar filename .Op Fl o Ar output .Op Fl P Ar options .Op Fl r Ar retries .Op Fl s Ar [trans::][community@][server][:port] .Op Fl t Ar timeout .Op Fl U Ar options .Op Fl v Ar version .Ar OID Ns = Ar syntax Ns : Ns Ar value .Op Ar OID Ns = Ar syntax Ns : Ns Ar value ... .Sh DESCRIPTION .Nm , .Nm bsnmpwalk and .Nm bsnmpset are simple tools for retrieving management information from and setting management information to a Simple Network Management Protocol (SNMP) agent. .Pp Depending on the options .Nm bsnmpget constructs either a SMNP GetRequest, GetNextRequest or a GetBulkRequest packet, fills in the object identifiers (OIDs) of the objects whose values will be retrived, waits for a response and prints it if received successfully. .Pp .Nm Bsnmpwalk queries an agent with ether SMNP GetNextRequest or GetBulkRequest packets, asking for values of OID instances that are a part of the object subtree rooted at the provided OIDs. .Pp .Nm Bsnmpset constructs a SMNP SetRequest packet, fills in the OIDs (object identifiers), syntaxes and values of the objects whose values are to be set and waits for a response from server. .Sh OPTIONS -.Pp The options are as follows (not all apply to all three programs): .Bl -tag -width ".It Fl D Ar options" .It Fl A Ar options Authentication options to use with SNMPv3 PDUs .Bl -tag -width \& .It Cm proto=[md5|sha] The protocol to use when calculating the PDU message digest. .It Cm key=authkey A binary localized authentication key to use when calculating the PDU message digest. .El .Pp By default SNMPv3 PDUs are sent unauthenticated. .It Fl a Skip any sanity checks when adding OIDs to a Protocol Data Unit (PDU): ingore syntax/access type, allow adding of non-leaf objects for GetPdu and read-only objects to a SetPDU. .It Fl b Ar buffersize Tune the size of buffers used to send and receive packets. The default size is 10000 bytes which should be enough unless an agent sends a really large octetstring. The maximum allowed length is 65535 according to the Structure of Management Information (SMIv2). .It Fl C Ar options The context to query with SNMPv3 PDUs. .Bl -tag -width \& .It Cm context=name The context name. Default is "" (empty). .It Cm context-engine=engine-id The SNMP Engine ID of the context to query with SNMPv3 PDUs, represented as binary octet string. By default, this is set to the Engine ID of the SNMP agent. .El .It Fl D Perform SNMP USM Engine Discovery, rather than sending a request for the value of a specific object. .It Fl d Turn on debugging. This option will cause the packets sent and received to be dumped to the terminal. .It Fl e Retry on error. If an error is returned in the response PDU, resend the request removing the variable that caused the error until a valid response is received. This is only useful for a GetRequest- and a GetNextRequest-PDU. .It Fl h Print a short help text with default values for various options. .It Fl I Ar options Load each MIB description file from the given list to translate symbolic object names to their numerical representation and vice versa. Use the other options to obtain a non-default behaviour: .Bl -tag -width \& .It Cm cut=OID Specifies the initial OID that was cut by .Xr gensnmpdef 1 when producing the MIB description file. The default value is .iso(1).org(3).dod(6) which is what should have been used for all the files installed under /usr/share/snmp/defs. Use this only if you generated your own files, providing a .Fl c option to .Xr gensnmpdef 1 . .It Cm path=filedir The directory where files in the list will be searched. The default is .Pa /usr/share/snmp/defs Ns . .It Cm file=filelist A comma separated list of files to which the two options above will apply. .El .Pp The file suboption has to come after the other suboptions so that their non-default values will be applied to the list of files. The order of the other suboptions before each file suboption can be random. Suboptions may be separated either by commas or by spaces. If using spaces make sure the entire option string is one argument, for example using quotes. .It Fl i Ar filelist List of MIB description files produced by .Xr gensnmpdef 1 which .Nm bsnmpget , .Nm bsnmpwalk or .Nm bsnmpset will search to translate numerical OIDs to their symbolic object names. Multiple files can be provided either giving this option multiple times or a comma separated list of file names. If a filename begins with a letter the default directory, /usr/share/snmp/defs, will be searched. .It Fl K Calculate and display the localized authentication and privacy keys corresponding to a plain text password. The password is obtain via the environment. Additionally, if one or more OIDs are specified, the calculated keys are used when processing the SNMPv3 requests. .It Fl l Ar filename The path of the posix local (unix domain) socket if local transport is used. .It Fl M Ar max-repetitions The value for the max-repetitions field in a GetBulk PDU. Default is 10. .It Fl N Ar non-repeaters The value for the non-repeaters field in a GetBulk PDU. Default is 0. .It Fl n Only use numerical representations for input and output OIDs and do not try to resolve symbolic object names. Note that .Nm bsnmpget , .Nm bsnmpwalk and .Nm bsnmpset will print numerical OIDs anyway if the corresponding string representation is not found in the MIB description files. .It Fl o Ar [quiet|short|verbose] The format used to print the received response. Quiet only prints values, short (default) prints an abbreviated OID representation and the value. In addition to the short output verbose prints the type before the value. .It Fl P Ar options Privacy options to use with SNMPv3 PDUs .Bl -tag -width \& .It Cm proto=[aes|des] The protocol to use when encypting/decrypting SNMPv3 PDU data. .It Cm key=privkey A binary localized privacy key to use when encypting/decrypting SNMPv3 PDU data. .El .Pp By default plain text SNMPv3 PDUs are sent. .It Fl p Ar [get|getnext|getbulk] The PDU type to send by .Nm bsmpget and .Nm bsnmpwalk . Default is get for .Nm bsmpget and getnext for .Nm bsnmpwalk . Getbulk allows executing the so called SNMP "bulkwalks" allowing the values of multiple columns to be retrived in a single PDU by .Nm bsnmpwalk . .It Fl r Ar retries Number of resends of request packets before giving up if the agent does not respond after the first try. Default is 3. .It Fl s Ar [trans::] Ns Ar [community@] Ns Ar [server] Ns Ar [:port] Each of the server specification components is optional but at least one has to be provided if .Ar s option is used. The server specification is constructed in the following manner: .Bl -tag -width \& .It Cm trans:: Transport type may be one of udp, stream or dgram. If this option is not provided an udp inet/inet6 socket will be used, which is the most common. Stream stands for a posix local stream socket and a posix local datagram socket will be used if dgram is specified. .It Cm community@ Specify an SNMP community string to be used when sending packets. If the option is skipped the default "public" will be used for .Nm and .Nm bsnmpwalk and the default "private" community string will be used for .Nm bsnmpset . .It Cm server This might be either the IP address or the hostname where the agent is listening. The default is .Qq localhost . .It Cm port The destination port to send the requests to. This is useful if the SNMP agent listens on a non-default port. Default is given by the .Qq snmp entry in .Pa /etc/services , port 161. .El .It Fl t Ar timeout Number of seconds before resending a request packet if the agent does not respond. The default value is 3 seconds. .It Fl U Ar options User credentials when sending SNMPv3 PDUs. .Bl -tag -width \& .It Cm engine=id The Engine ID of the SNMP agent represented as a binary octet string. .It Cm engine-boots=value The value of the snmpEngineBoots of the SNMP agent. .It Cm engine-time=value The value of the snmpEngineTime of the SNMP agent. .Pp If any of the above is not specified, SNMP USM Engine Discovery is attempted. This is also the default behavior. .It Cm name=username The USM user name to include in the SNMPv3 PDUs. By default, the user name is obtain via the environment .El .It Fl v Ar version The SNMP protocol version to use when sending requests. SNMP versions 1, 2 and 3 are supported. If no version option is provided .Nm bsnmpget , .Nm bsnmpwalk and .Nm bsnmpset will use version 2. Note that GetBulkRequest-PDUs were introduced in SNMPv2 thus setting the version to 1 is incompatiable with sending a GetBulk PDU. .It OID The object identifier whose value to retrive. At least one OID should be provided for .Nm bsnmpget to be able to send a request. .Pp For .Nm bsnmpwalk this is the root object identifier of the subtree whose values are to be retrived. If no OID is provided .Nm bsnmpwalk will walk the mib2 subtree rooted at .iso(1).org(3).dod(6).internet(1).mgmt(2).mib2(1) . .Pp Any of the formats used to print a single variable is valid as input OID: .Bl -tag -width \& .It 1.3.6.1.2.1.25.1.1.0 .It sysDescr .It ifPhysAddress.1 .It ifRcvAddressStatus.2.6.255.255.255.255.255.255 .It ifRcvAddressType[2,ff:ff:ff:ff:ff:ff] .It ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff] (requires .Fl o Ar verbose option) .El .Pp Square brackets are used to denote an entry's indexes. When used in an input OID, the square brackets may have to be escaped or the OID has to be quoted to protect it from the shell. Note there is no difference between ifName.1 and "ifName[1]". .It OID Ns = Ns Ar [syntax Ns :] Ns Ar value The object identifier with its syntax type and value that is to be set. At least one such string OID=[syntax:]value should be provided to .Nm bsnmpset to be able to send a request. .Bl -tag -width \& .It Cm OID OID may be input as a string, a string followed by a random number of integers (suboids) separated by dots, a sequence of integers separated by dots - that is if .Ar n options is used - and in such case a syntax is required for every value, or a string followed by square brackets (used to denote an entry's indexes) and corresponding indexes. Any of formats used to print a single variable by .Nm bsnmpset is valid for inpit OID as well: .Bl -tag -width \& .It 1.3.6.1.2.1.25.1.1.0=TimeTicks:537615486 .It sysLocation=OctetString:"@ Home" (with Fl o Ar verbose No option) .It sysLocation.0="@ Home" .It 1.3.6.1.2.1.2.2.1.6.1=OctetString:ffffffffffff .It ifPhysAddress.1="00:02:b3:1d:1c:a3" .It ifRcvAddressStatus.1.6.255.255.255.255.255.255=1 .It "ifRcvAddressStatus[Integer:1,OctetString:ff:ff:ff:ff:ff:ff]=Integer:1" (with .Fl o Ar verbose option) .El .It Cm syntax where syntax string is one of: Integer, OctetString, OID, IpAddress, Counter32, Gauge, TimeTicks, Counter64. .It Cm value The value to be set - IP address in form of u.u.u.u - for example 1.3.1.6.1.2.0=IpAddress:192.168.0.1, strings require inverted-commas if they contain any special characters or spaces, all other numeric types don't. .El .El .Sh ENVIRONMENT .Nm , .Nm bsnmpwalk and .Nm bsnmpset use the following environment variables: .Bl -tag -width SNMPAUTH .It Ev SNMPAUTH Specifies a default SNMP USM authentication protocol. .It Ev SNMPPRIV Specifies a default SNMP USM privacy protocol. .It Ev SNMPUSER Specifies a default SNMP USM user name. .It Ev SNMPPASSWD Specifies the SNMP USM plain text password to use when calculating localized authentication and privacy keys. If this variable exists in the environment, SMNPv3 is the default version to use for outgoing requests. .El .Sh SEE ALSO .Xr gensnmpdef 1 .Sh AUTHORS .An Shteryana Shopova Aq syrinx@FreeBSD.org diff --git a/usr.sbin/ctladm/ctladm.8 b/usr.sbin/ctladm/ctladm.8 index 18333d907d5c..d4d044f6c8b2 100644 --- a/usr.sbin/ctladm/ctladm.8 +++ b/usr.sbin/ctladm/ctladm.8 @@ -1,989 +1,986 @@ .\" .\" Copyright (c) 2003 Silicon Graphics International Corp. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions, and the following disclaimer, .\" without modification. .\" 2. Redistributions in binary form must reproduce at minimum a disclaimer .\" substantially similar to the "NO WARRANTY" disclaimer below .\" ("Disclaimer") and any redistribution must be conditioned upon .\" including a substantially similar Disclaimer requirement for further .\" binary redistribution. .\" .\" NO WARRANTY .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS .\" "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT .\" LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTIBILITY AND FITNESS FOR .\" A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT .\" HOLDERS OR CONTRIBUTORS BE LIABLE FOR SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING .\" IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE .\" POSSIBILITY OF SUCH DAMAGES. .\" .\" ctladm utility man page. .\" .\" Author: Ken Merry .\" .\" $Id: //depot/users/kenm/FreeBSD-test2/usr.sbin/ctladm/ctladm.8#3 $ .\" $FreeBSD$ .\" .Dd March 6, 2012 .Dt CTLADM 8 .Os .Sh NAME .Nm ctladm .Nd CAM Target Layer control utility .Sh SYNOPSIS .Nm .Aq Ar command .Op target:lun .Op generic args .Op command args .Nm .Ic tur .Aq target:lun .Op general options .Nm .Ic inquiry .Aq target:lun .Op general options .Nm .Ic reqsense .Aq target:lun .Op general options .Nm .Ic reportluns .Aq target:lun .Op general options .Nm .Ic read .Aq target:lun .Op general options .Aq Fl l Ar lba .Aq Fl d Ar datalen .Aq Fl f Ar file|- .Aq Fl b Ar blocksize_bytes .Op Fl c Ar cdbsize .Op Fl N .Nm .Ic write .Aq target:lun .Op general options .Aq Fl l Ar lba .Aq Fl d Ar datalen .Aq Fl f Ar file|- .Aq Fl b Ar blocksize_bytes .Op Fl c Ar cdbsize .Op Fl N .Nm .Ic bbrread .Aq target:lun .Op general options .Aq Fl -l Ar lba .Aq Fl -d Ar datalen .Nm .Ic readcap .Aq target:lun .Op general options .Op Fl c Ar cdbsize .Nm .Ic modesense .Aq target:lun .Aq Fl m Ar page | Fl l .Op Fl P Ar pc .Op Fl d .Op Fl S Ar subpage .Op Fl c Ar size .Nm .Ic start .Aq target:lun .Op general options .Op Fl i .Op Fl o .Nm .Ic stop .Aq target:lun .Op general options .Op Fl i .Op Fl o .Nm .Ic synccache .Aq target:lun .Op general options .Op Fl l Ar lba .Op Fl b Ar blockcount .Op Fl r .Op Fl i .Op Fl c Ar cdbsize .Nm .Ic shutdown .Op general options .Nm .Ic startup .Op general options .Nm .Ic hardstop .Nm .Ic hardstart .Nm .Ic lunlist .Nm .Ic delay .Aq target:lun .Aq Fl l Ar datamove|done .Aq Fl t Ar secs .Op Fl T Ar oneshot|cont .Nm .Ic realsync Aq on|off|query .Nm .Ic setsync interval .Aq target:lun .Aq Fl i Ar interval .Nm .Ic getsync .Aq target:lun .Nm .Ic inject .Aq Fl i Ar action .Aq Fl p Ar pattern .Op Fl r Ar lba,len .Op Fl s Ar len fmt Op Ar args .Op Fl c .Op Fl d Ar delete_id .Nm .Ic create .Aq Fl b Ar backend .Op Fl B Ar blocksize .Op Fl d Ar device_id .Op Fl l Ar lun_id .Op Fl o Ar name=value .Op Fl s Ar size_bytes .Op Fl S Ar serial_num .Op Fl t Ar device_type .Nm .Ic remove .Aq Fl b Ar backend .Aq Fl l Ar lun_id .Op Fl o Ar name=value .Nm .Ic modify .Aq Fl b Ar backend .Aq Fl l Ar lun_id .Aq Fl s Ar size_bytes .Nm .Ic devlist .Op Fl b Ar backend .Op Fl v .Op Fl x .Nm .Ic port .Op Fl l .Op Fl o Ar on|off .Op Fl w Ar wwpn .Op Fl W Ar wwnn .Op Fl p Ar targ_port .Op Fl t Ar fe_type .Op Fl q .Op Fl x .Nm .Ic dumpooa .Nm .Ic dumpstructs .Nm .Ic help .Sh DESCRIPTION The .Nm utility is designed to provide a way to access and control the CAM Target Layer (CTL). It provides a way to send .Tn SCSI commands to the CTL layer, and also provides some meta-commands that utilize .Tn SCSI commands. (For instance, the .Ic lunlist command is implemented using the .Tn SCSI REPORT LUNS and INQUIRY commands.) .Pp The .Nm utility has a number of primary functions, many of which require a device identifier. The device identifier takes the following form: .Bl -tag -width 14n .It target:lun Specify the target (almost always 0) and LUN number to operate on. .El Many of the primary functions of the .Nm utility take the following optional arguments: -.Pp .Bl -tag -width 10n .It Fl C Ar retries Specify the number of times to retry a command in the event of failure. .It Fl D Ar device Specify the device to open. This allows opening a device other than the default device, .Pa /dev/cam/ctl , to be opened for sending commands. .It Fl I Ar id Specify the initiator number to use. By default, .Nm will use 7 as the initiator number. .El .Pp Primary commands: .Bl -tag -width 11n .It Ic tur Send the .Tn SCSI TEST UNIT READY command to the device and report whether or not it is ready. .It Ic inquiry Send the .Tn SCSI INQUIRY command to the device and display some of the returned inquiry data. .It Ic reqsense Send the .Tn SCSI REQUEST SENSE command to the device and display the returned sense information. .It Ic reportluns Send the .Tn SCSI REPORT LUNS command to the device and display supported LUNs. .It Ic read Send a .Tn SCSI READ command to the device, and write the requested data to a file or stdout. .Bl -tag -width 12n .It Fl l Ar lba Specify the starting Logical Block Address for the READ. This can be specified in decimal, octal (starting with 0), hexadecimal (starting with 0x) or any other base supported by .Xr strtoull 3 . .It Fl d Ar datalen Specify the length, in 512 byte blocks, of the READ request. .It Fl f Ar file Specify the destination for the data read by the READ command. Either a filename or .Sq - for stdout may be specified. .It Fl c Ar cdbsize Specify the minimum .Tn SCSI CDB (Command Data Block) size to be used for the READ request. Allowable values are 6, 10, 12 and 16. Depending upon the LBA and amount of data requested, a larger CDB size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) .It Fl b Ar blocksize Specify the blocksize of the underlying .Tn SCSI device, so the transfer length can be calculated accurately. The blocksize can be obtained via the .Tn SCSI READ CAPACITY command. .It Fl N Do not copy data to .Nm from the kernel when doing a read, just execute the command without copying data. This is to be used for performance testing. .El .It Ic write Read data from a file or stdin, and write the data to the device using the .Tn SCSI WRITE command. .Bl -tag -width 12n .It Fl l Ar lba Specify the starting Logical Block Address for the WRITE. This can be specified in decimal, octal (starting with 0), hexadecimal (starting with 0x) or any other base supported by .Xr strtoull 3 . .It Fl d Ar atalen Specify the length, in 512 byte blocks, of the WRITE request. .It Fl f Ar file Specify the source for the data to be written by the WRITE command. Either a filename or .Sq - for stdin may be specified. .It Fl c Ar cdbsize Specify the minimum .Tn SCSI CDB (Command Data Block) size to be used for the READ request. Allowable values are 6, 10, 12 and 16. Depending upon the LBA and amount of data requested, a larger CDB size may be used to satisfy the request. (e.g., for LBAs above 0xffffffff, READ(16) must be used to satisfy the request.) .It Fl b Ar blocksize Specify the blocksize of the underlying .Tn SCSI device, so the transfer length can be calculated accurately. The blocksize can be obtained via the .Tn SCSI READ CAPACITY command. .It Fl N Do not copy data to .Nm to the kernel when doing a write, just execute the command without copying data. This is to be used for performance testing. .El .It Ic bbrread Issue a SCSI READ command to the logical device to potentially force a bad block on a disk in the RAID set to be reconstructed from the other disks in the array. This command should only be used on an array that is in the normal state. If used on a critical array, it could cause the array to go offline if the bad block to be remapped is on one of the disks that is still active in the array. .Pp The data for this particular command will be discarded, and not returned to the user. .Pp In order to determine which LUN to read from, the user should first determine which LUN the disk with a bad block belongs to. Then he should map the bad disk block back to the logical block address for the array in order to determine which LBA to pass in to the .Ic bbrread command. .Pp This command is primarily intended for testing. In practice, bad block remapping will generally be triggered by the in-kernel Disk Aerobics and Disk Scrubbing code. .Bl -tag -width 10n .It Fl l Ar lba Specify the starting Logical Block Address. .It Fl d Ar datalen Specify the amount of data in bytes to read from the LUN. This must be a multiple of the LUN blocksize. .El .It Ic readcap Send the .Tn SCSI READ CAPACITY command to the device and display the device size and device block size. By default, READ CAPACITY(10) is used. If the device returns a maximum LBA of 0xffffffff, however, .Nm will automatically issue a READ CAPACITY(16), which is implemented as a service action of the SERVICE ACTION IN(16) opcode. The user can specify the minimum CDB size with the .Fl c argument. Valid values for the .Fl c option are 10 and 16. If a 10 byte CDB is specified, the request will be automatically reissued with a 16 byte CDB if the maximum LBA returned is 0xffffffff. .It Ic modesense Send a .Tn SCSI MODE SENSE command to the device, and display the requested mode page(s) or page list. .Bl -tag -width 10n .It Fl m Ar page Specify the mode page to display. This option and the .Fl l option are mutually exclusive. One of the two must be specified, though. Mode page numbers may be specified in decimal or hexadecimal. .It Fl l Request that the list of mode pages supported by the device be returned. This option and the .Fl m option are mutually exclusive. One of the two must be specified, though. .It Fl P Ar pc Specify the mode page page control value. Possible values are: .Bl -tag -width 2n -compact .It 0 Current values. .It 1 Changeable value bitmask. .It 2 Default values. .It 3 Saved values. .El .It Fl d Disable block descriptors when sending the mode sense request. .It Fl S Ar subpage Specify the subpage used with the mode sense request. .It Fl c Ar cdbsize Specify the CDB size used for the mode sense request. Supported values are 6 and 10. .El .It Ic start Send the .Tn SCSI START STOP UNIT command to the specified LUN with the start bit set. .Bl -tag -width 4n .It Fl i Set the immediate bit in the CDB. Note that CTL does not support the immediate bit, so this is primarily useful for making sure that CTL returns the proper error. .It Fl o Set the Copan proprietary on/offline bit in the CDB. When this flag is used, the LUN will be marked online again (see the description of the .Ic shutdown and .Ic startup commands). When this flag is used with a start command, the LUN will NOT be spun up. You need to use a start command without the .Fl o flag to spin up the disks in the LUN. .El .It Ic stop Send the .Tn SCSI START STOP UNIT command to the specified LUN with the start bit cleared. We use an ordered tag to stop the LUN, so we can guarantee that all pending I/O executes before it is stopped. (CTL guarantees this anyway, but .Nm sends an ordered tag for completeness.) .Bl -tag -width 4n .It Fl i Set the immediate bit in the CDB. Note that CTL does not support the immediate bit, so this is primarily useful for making sure that CTL returns the proper error. .It Fl o Set the Copan proprietary on/offline bit in the CDB. When this flag is used, the LUN will be spun down and taken offline ("Logical unit not ready, manual intervention required"). See the description of the .Ic shutdown and .Ic startup options. .El .It Ic synccache Send the .Tn SCSI SYNCHRONIZE CACHE command to the device. By default, SYNCHRONIZE CACHE(10) is used. If the specified starting LBA is greater than 0xffffffff or the length is greater than 0xffff, though, SYNCHRONIZE CACHE(16) will be used. The 16 byte command will also be used if the user specifies a 16 byte CDB with the .Fl c argument. .Bl -tag -width 14n .It Fl l Ar lba Specify the starting LBA of the cache region to synchronize. This option is a no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN. .It Fl b Ar blockcount Specify the length of the cache region to synchronize. This option is a no-op for CTL. If you send a SYNCHRONIZE CACHE command, it will sync the cache for the entire LUN. .It Fl r Specify relative addressing for the starting LBA. CTL does not support relative addressing, since it only works for linked commands, and CTL doesn't support linked commands. .It Fl i Tell the target to return status immediately after issuing the SYHCHRONIZE CACHE command rather than waiting for the cache to finish syncing. CTL does not support this bit. .It Fl c Ar cdbsize Specify the minimum CDB size. Valid values are 10 and 16 bytes. .El .It Ic shutdown Issue a .Tn SCSI START STOP UNIT command with the start bit cleared and the on/offline bit set to all direct access LUNs. This will spin down all direct access LUNs, and mark them offline ("Logical unit not ready, manual intervention required"). Once marked offline, the state can only be cleared by sending a START STOP UNIT command with the start bit set and the on/offline bit set. The .Nm commands .Ic startup and .Ic start will accomplish this. Note that the on/offline bit is a non-standard Copan extension to the .Tn SCSI START STOP UNIT command, so merely sending a normal start command from an initiator will not clear the condition. (This is by design.) .It Ic startup Issue a .Tn SCSI START STOP UNIT command with the start bit set and the on/offline bit set to all direct access LUNs. This will mark all direct access LUNs "online" again. It will not cause any LUNs to start up. A separate start command without the on/offline bit set is necessary for that. .It Ic hardstop Use the kernel facility for stopping all direct access LUNs and setting the offline bit. Unlike the .Ic shutdown command above, this command allows shutting down LUNs with I/O active. It will also issue a LUN reset to any reserved LUNs to break the reservation so that the LUN can be stopped. .Ic shutdown command instead. .It Ic hardstart This command is functionally identical to the .Ic startup command described above. The primary difference is that the LUNs are enumerated and commands sent by the in-kernel Front End Target Driver instead of by .Nm . .It Ic lunlist List all LUNs registered with CTL. Because this command uses the ioctl port, it will only work when the FETDs (Front End Target Drivers) are enabled. This command is the equivalent of doing a REPORT LUNS on one LUN and then and then an INQUIRY on each LUN in the system. .It Ic delay Delay commands at the given location. There are two places where commands may be delayed currently: before data is transferred .Pq Dq datamove and just prior to sending status to the host .Pq Dq done . One of the two must be supplied as an argument to the .Fl l option. The .Fl t option must also be specified. .Bl -tag -width 12n .It Fl l Ar delayloc Delay command(s) at the specified location. This can either be at the data movement stage (datamove) or prior to command completion (done). .It Fl t Ar delaytime Delay command(s) for the specified number of seconds. This must be specified. If set to 0, it will clear out any previously set delay for this particular location (datamove or done). .It Fl T Ar delaytype Specify the delay type. By default, the .Ic delay option will delay the next command sent to the given LUN. With the .Fl T Ar cont option, every command will be delayed by the specified period of time. With the .Fl T Ar oneshot the next command sent to the given LUN will be delayed and all subsequent commands will be completed normally. This is the default. .El .It Ic realsync Query and control CTL's SYNCHRONIZE CACHE behavior. The .Sq query argument will show whether SYNCHRONIZE CACHE commands are being sent to the backend or not. The default is to send SYNCHRONIZE CACHE commands to the backend. The .Sq on argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be sent to the backend. The .Sq off argument will cause all SYNCHRONIZE CACHE commands sent to all LUNs to be immediately returned to the initiator with successful status. .It Ic setsync For a given lun, only actually service every Nth SYNCHRONIZE CACHE command that is sent. This can be used for debugging the optimal time period for sending SYNCHRONIZE cache commands. An interval of 0 means that the cache will be flushed for this LUN every time a SYNCHRONIZE CACHE command is received. .Pp You must specify the target and LUN you want to modify. .It Ic getsync Get the interval at which we actually service the SYNCHRONIZE CACHE command, as set by the .Ic setsync command above. The reported number means that we will actually flush the cache on every Nth SYNCHRONIZE CACHE command. A value of 0 means that we will flush the cache every time. .Pp You must specify the target and LUN you want to query. .It Ic inject Inject the specified type of error for the LUN specified, when a command that matches the given pattern is seen. The sense data returned is in either fixed or descriptor format, depending upon the status of the D_SENSE bit in the control mode page (page 0xa) for the LUN. .Pp Errors are only injected for commands that have not already failed for other reasons. By default, only the first command matching the pattern specified is returned with the supplied error. .Pp If the .Fl c flag is specified, all commands matching the pattern will be returned with the specified error until the error injection command is deleted with .Fl d flag. .Bl -tag -width 17n .It Fl i Ar action Specify the error to return: .Bl -tag -width 10n .It aborted Return the next matching command on the specified LUN with the sense key ABORTED COMMAND (0x0b), and the ASC/ASCQ 0x45,0x00 ("Select or reselect failure"). .It mediumerr Return the next matching command on the specified LUN with the sense key MEDIUM ERROR (0x03) and the ASC/ASCQ 0x11,0x00 ("Unrecovered read error") for reads, or ASC/ASCQ 0x0c,0x02 ("Write error - auto reallocation failed") for write errors. .It ua Return the next matching command on the specified LUN with the sense key UNIT ATTENTION (0x06) and the ASC/ASCQ 0x29,0x00 ("POWER ON, RESET, OR BUS DEVICE RESET OCCURRED"). .It custom Return the next matching command on the specified LUN with the supplied sense data. The .Fl s argument must be specified. .El .It Fl p Ar pattern Specify which commands should be returned with the given error. .Bl -tag -width 10n .It read The error should apply to READ(6), READ(10), READ(12), READ(16), etc. .It write The error should apply to WRITE(6), WRITE(10), WRITE(12), WRITE(16), WRITE AND VERIFY(10), etc. .It rw The error should apply to both read and write type commands. .It readcap The error should apply to READ CAPACITY(10) and READ CAPACITY(16) commands. .It tur The error should apply to TEST UNIT READY commands. .It any The error should apply to any command. .El .It Fl r Ar lba,len Specify the starting lba and length of the range of LBAs which should trigger an error. This option is only applies when read and/or write patterns are specified. If used with other command types, the error will never be triggered. .It Fl s Ar len fmt Op Ar args Specify the sense data that is to be returned for custom actions. If the format is .Sq - , len bytes of sense data will be read from standard input and written to the sense buffer. If len is longer than 252 bytes (the maximum allowable .Tn SCSI sense data length), it will be truncated to that length. The sense data format is described in .Xr cam_cdparse 3 . .It Fl c The error injection should be persistent, instead of happening once. Persistent errors must be deleted with the .Fl d argument. .It Fl d Ar delete_id Delete the specified error injection serial number. The serial number is returned when the error is injected. .El .It Ic port Perform one of several CTL frontend port operations. Either get a list of frontend ports .Pq Fl l , turn one or more frontends on or off .Pq Fl o Ar on|off , or set the World Wide Node Name .Pq Fl w Ar wwnn or World Wide Port Name .Pq Fl W Ar wwpn for a given port. One of .Fl l , .Fl o , or .Fl w or .Fl W must be specified. The WWNN and WWPN may both be specified at the same time, but cannot be combined with enabling/disabling or listing ports. .Bl -tag -width 12n .It Fl l List all CTL frontend ports or a specific port type or number. .It Fl o Ar on|off Turn the specified CTL frontend ports off or on. If no port number or port type is specified, all ports are turned on or off. .It Fl p Ar targ_port Specify the frontend port number. The port numbers can be found in the frontend port list. .It Fl q Omit the header in the port list output. .It Fl t Ar fe_type Specify the frontend type. Currently defined port types are .Dq fc (Fibre Channel), .Dq scsi (Parallel SCSI), .Dq ioctl (CTL ioctl interface), and .Dq internal (CTL CAM SIM). .It Fl w Ar wwnn Set the World Wide Node Name for the given port. The .Fl n argument must be specified, since this is only possible to implement on a single port. As a general rule, the WWNN should be the same across all ports on the system. .It Fl W Ar wwpn Set the World Wide Node Name for the given port. The .Fl n argument must be specified, since this is only possible to implement on a single port. As a general rule, the WWPN must be different for every port in the system. .It Fl x Output the port list in XML format. .El .It Ic dumpooa Dump the OOA (Order Of Arrival) queue for each LUN registered with CTL. .It Ic dumpstructs Dump the CTL structures to the console. .It Ic create Create a new LUN. The backend must be specified, and depending upon the backend requested, some of the other options may be required. If the LUN is created successfully, the LUN configuration will be displayed. If LUN creation fails, a message will be displayed describing the failure. .Bl -tag -width 14n .It Fl b Ar backend The .Fl b flag is required. This specifies the name backend to use when creating the LUN. Examples are .Dq ramdisk and .Dq block . .It Fl B Ar blocksize Specify the blocksize of the backend in bytes. .It Fl d Ar device_id Specify the LUN-associated string to use in the .Tn SCSI INQUIRY VPD page 0x83 data. .It Fl l Ar lun_id Request that a particular LUN number be assigned. If the requested LUN number is not available, the request will fail. .It Fl o Ar name=value Specify a backend-specific name/value pair. Multiple .Fl o arguments may be specified. Refer to the backend documentation for arguments that may be used. .It Fl s Ar size_bytes Specify the size of the LUN in bytes. Some backends may allow setting the size (e.g. the ramdisk backend) and for others the size may be implicit (e.g. the block backend). .It Fl S Ar serial_num Specify the serial number to be used in the .Tn SCSI INQUIRY VPD page 0x80 data. .It Fl t Ar device_type Specify the numeric SCSI device type to use when creating the LUN. For example, the Direct Access type is 0. If this flag is not used, the type of LUN created is backend-specific. Not all LUN types are supported. Currently CTL only supports Direct Access (type 0) and Processor (type 3) LUNs. The backend requested may or may not support all of the LUN types that CTL supports. .El .It Ic remove Remove a LUN. The backend must be specified, and the LUN number must also be specified. Backend-specific options may also be specified with the .Fl o flag. .Bl -tag -width 14n .It Fl b Ar backend Specify the backend that owns the LUN to be removed. Examples are .Dq ramdisk and .Dq block . .It Fl l Ar lun_id Specify the LUN number to remove. .It Fl o Ar name=value Specify a backend-specific name/value pair. Multiple .Fl o arguments may be specified. Refer to the backend documentation for arguments that may be used. .El .It Ic modify Modify a LUN size. The backend, the LUN number, and the size must be specified. .Bl -tag -width 14n .It Fl b Ar backend Specify the backend that owns the LUN to be removed. Examples are .Dq ramdisk and .Dq block . .It Fl l Ar lun_id Specify the LUN number to remove. .It Fl s Ar size_bytes Specify the size of the LUN in bytes. For the .Dq block backend, an .Dq auto keyword may be passed instead; this will make CTL use the size of backing file or device. .El .It Ic devlist Get a list of all configured LUNs. This also includes the LUN size and blocksize, serial number and device ID. .Bl -tag -width 11n .It Fl b Ar backend Specify the backend. This restricts the LUN list to the named backend. Examples are .Dq ramdisk and .Dq block . .It Fl v Be verbose. This will also display any backend-specific LUN attributes in addition to the standard per-LUN information. .It Fl x Dump the raw XML. The LUN list information from the kernel comes in XML format, and this option allows the display of the raw XML data. This option and the .Fl v and .Fl b options are mutually exclusive. If you specify .Fl x , the entire LUN database is displayed in XML format. .El .It Ic help Display .Nm usage information. .El .Sh EXAMPLES .Dl ctladm tur 0:1 .Pp Send a .Tn SCSI TEST UNIT READY command to LUN 1. .Pp .Dl ctladm modesense 0:1 -l .Pp Display the list of mode pages supported by LUN 1. .Pp .Dl ctladm modesense 0:0 -m 10 -P 3 -d -c 10 .Pp Display the saved version of the Control mode page (page 10) on LUN 0. Disable fetching block descriptors, and use a 10 byte MODE SENSE command instead of the default 6 byte command. -.Pp .Bd -literal ctladm read 0:2 -l 0 -d 1 -b 512 -f - > foo .Ed .Pp Read the first 512 byte block from LUN 2 and dump it to the file .Pa foo . .Bd -literal ctladm write 0:3 -l 0xff432140 -d 20 -b 512 -f /tmp/bar .Ed .Pp Read 10240 bytes from the file .Pa /tmp/bar and write it to target 0, LUN 3. starting at LBA 0xff432140. .Pp .Dl ctladm create -b ramdisk -s 10485760000000000 .Pp Create a LUN with the .Dq fake ramdisk as a backing store. The LUN will claim to have a size of approximately 10 terabytes. .Pp .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 .Pp Create a LUN using the block backend, and specify the file .Pa src/usr.sbin/ctladm/ctladm.8 as the backing store. The size of the LUN will be derived from the size of the file. .Pp .Dl ctladm create -b block -o file=src/usr.sbin/ctladm/ctladm.8 -S MYSERIAL321 -d MYDEVID123 .Pp Create a LUN using the block backend, specify the file .Pa src/usr.sbin/ctladm/ctladm.8 as the backing store, and specify the .Tn SCSI VPD page 0x80 and 0x83 serial number ( .Fl S) and device ID ( .Fl d). .Pp .Dl ctladm remove -b block -l 12 .Pp Remove LUN 12, which is handled by the block backend, from the system. .Pp .Dl ctladm devlist .Pp List configured LUNs in the system, along with their backend and serial number. This works when the Front End Target Drivers are enabled or disabled. .Pp .Dl ctladm lunlist .Pp List all LUNs in the system, along with their inquiry data and device type. This only works when the FETDs are enabled, since the commands go through the ioctl port. .Pp .Dl ctladm inject 0:6 -i mediumerr -p read -r 0,512 -c .Pp Inject a medium error on LUN 6 for every read that covers the first 512 blocks of the LUN. -.Pp .Bd -literal -offset indent ctladm inject 0:6 -i custom -p tur -s 18 "f0 0 02 s12 04 02" .Ed .Pp Inject a custom error on LUN 6 for the next TEST UNIT READY command only. This will result in a sense key of NOT READY (0x02), and an ASC/ASCQ of 0x04,0x02 ("Logical unit not ready, initializing command required"). .Sh SEE ALSO .Xr cam 3 , .Xr cam_cdbparse 3 , .Xr cam 4 , .Xr xpt 4 , .Xr camcontrol 8 .Sh HISTORY The .Nm utility was originally written during the Winter/Spring of 2003 as an interface to CTL. .Sh AUTHORS .An Ken Merry Aq ken@FreeBSD.org diff --git a/usr.sbin/ifmcstat/ifmcstat.8 b/usr.sbin/ifmcstat/ifmcstat.8 index 9794d70a44df..015184a0274d 100644 --- a/usr.sbin/ifmcstat/ifmcstat.8 +++ b/usr.sbin/ifmcstat/ifmcstat.8 @@ -1,131 +1,130 @@ .\" $KAME: ifmcstat.8,v 1.6 2002/10/31 04:23:43 suz Exp $ .\" .\" Copyright (c) 2007-2009 Bruce Simpson. .\" Copyright (C) 1995, 1996, 1997, 1998, and 1999 WIDE Project. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the project nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE PROJECT AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE PROJECT OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 27, 2009 .Dt IFMCSTAT 8 .Os .Sh NAME .Nm ifmcstat .Nd dump multicast group management statistics per interface .Sh SYNOPSIS .Nm .Op Fl i Ar interface .Op Fl f Ar address-family .Op Fl v .Op Fl K .Op Fl M Ar core .Op Fl N Ar system .\" .Sh DESCRIPTION The .Nm command dumps multicast group information from the kernel. .Pp The following options are supported: .Bl -tag -width Fl .It Fl i Ar interface specifies the interface to be displayed. .Pp .It Fl f Ar address-family specifies the address family to be displayed; .Ar inet , .Ar inet6 and .Ar link are supported. .It Fl v specifies that link-layer memberships should be printed; they are suppressed by default. It may not be specified for .Fl f Ar link . Source lists for each group will also be printed. .Pp If specified twice, and .Xr kvm 3 is in use, the control plane timers for each interface and the source list counters for each group will also be printed. .El .Pp The following options are only available if .Nm has been built with support for .Xr kvm 3 : .Bl -tag -width Fl .It Fl K attempts to use .Xr kvm 3 to retrieve the multicast group information. .It Fl M Ar core extracts values associated with the name list from the specified core, instead of the default .Pa /dev/kmem . .It Fl N Ar system extracts the name list from the specified kernel instead of the default, which is the kernel image the system has booted from. .El .Sh IMPLEMENTATION NOTES .Nm will always print the embedded scope IDs of IPv6 multicast group memberships. This is because memberships are always scoped to an interface. .Pp When run with the .Fl v option, .Nm may print multicast MAC addresses twice if they are referenced by a layer 3 protocol. .Pp When run with .Xr kvm 3 support, the names of all interfaces configured in the system will be printed in the first column of output, even if no multicast group memberships are present on those interfaces. The output may also be slightly different, as the kernel data structures are being traversed with minimal post-processing of the output. .Pp When built without .Xr kvm 3 support, the information displayed by .Nm is more limited. This support is recommended for debugging purposes. It requires super-user privilege if used to inspect a running kernel. -.Pp .Sh SEE ALSO .Xr netstat 1 , .Xr getifaddrs 3 , .Xr getifmaddrs 3 , .Xr kvm 3 diff --git a/usr.sbin/mfiutil/mfiutil.8 b/usr.sbin/mfiutil/mfiutil.8 index b948b953eae6..5ccdcdca72cf 100644 --- a/usr.sbin/mfiutil/mfiutil.8 +++ b/usr.sbin/mfiutil/mfiutil.8 @@ -1,607 +1,606 @@ .\" Copyright (c) 2008, 2009 Yahoo!, Inc. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The names of the authors may not be used to endorse or promote .\" products derived from this software without specific prior written .\" permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd September 2, 2011 .Dt MFIUTIL 8 .Os .Sh NAME .Nm mfiutil .Nd Utility for managing LSI MegaRAID SAS controllers .Sh SYNOPSIS .Nm .Cm version .Nm .Op Fl u Ar unit .Cm show adapter .Nm .Op Fl u Ar unit .Cm show battery .Nm .Op Fl d .Op Fl e .Op Fl u Ar unit .Cm show config .Nm .Op Fl u Ar unit .Cm show drives .Nm .Op Fl u Ar unit .Cm show events .Op Fl c Ar class .Op Fl l Ar locale .Op Fl n Ar count .Op Fl v .Op Ar start Op Ar stop .Nm .Op Fl u Ar unit .Cm show firmware .Nm .Op Fl u Ar unit .Cm show logstate .Nm .Op Fl d .Op Fl e .Op Fl u Ar unit .Cm show patrol .Nm .Op Fl d .Op Fl e .Op Fl u Ar unit .Cm show progress .Nm .Op Fl u Ar unit .Cm show volumes .Nm .Op Fl u Ar unit .Cm fail Ar drive .Nm .Op Fl u Ar unit .Cm good Ar drive .Nm .Op Fl u Ar unit .Cm rebuild Ar drive .Nm .Op Fl u Ar unit .Cm drive progress Ar drive .Nm .Op Fl u Ar unit .Cm drive clear Ar drive Brq "start | stop" .Nm .Op Fl u Ar unit .Cm start rebuild Ar drive .Nm .Op Fl u Ar unit .Cm abort rebuild Ar drive .Nm .Op Fl u Ar unit .Cm locate Ar drive Brq "on | off" .Nm .Op Fl u Ar unit .Cm cache Ar volume Op Ar setting Oo Ar value Oc Op ... .Nm .Op Fl u Ar unit .Cm name Ar volume Ar name .Nm .Op Fl u Ar unit .Cm volume progress Ar volume .Nm .Op Fl u Ar unit .Cm clear .Nm .Op Fl u Ar unit .Cm create Ar type .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Nm .Op Fl u Ar unit .Cm delete Ar volume .Nm .Op Fl u Ar unit .Cm add Ar drive Op Ar volume .Nm .Op Fl u Ar unit .Cm remove Ar drive .Nm .Op Fl u Ar unit .Cm start patrol .Nm .Op Fl u Ar unit .Cm stop patrol .Nm .Op Fl u Ar unit .Cm patrol Ar command Op Ar interval Op Ar start .Nm .Op Fl u Ar unit .Cm flash Ar file .Sh DESCRIPTION The .Nm utility can be used to display or modify various parameters on LSI MegaRAID SAS RAID controllers. Each invocation of .Nm consists of zero or more global options followed by a command. Commands may support additional optional or required arguments after the command. .Pp Currently one global option is supported: .Bl -tag -width indent .It Fl u Ar unit .Ar unit specifies the unit of the controller to work with. If no unit is specified, then unit 0 is used. .El .Pp Various commands accept either or both of the two options: .Bl -tag -width indent .It Fl d Print numeric device IDs as drive identifier. This is the default. Useful in combination with .Fl e to print both, numeric device IDs and enclosure:slot information. .It Fl e Print drive identifiers in enclosure:slot form. See next paragraph on format details in context of input rather than output. .El .Pp Drives may be specified in two forms. First, a drive may be identified by its device ID. The device ID for configured drives can be found in .Cm show config . Second, a drive may be identified by its location as .Sm off .Op E Ar xx Ns \&: .Li S Ns Ar yy .Sm on where .Ar xx is the enclosure and .Ar yy is the slot for each drive as displayed in .Cm show drives . .Pp Volumes may be specified in two forms. First, a volume may be identified by its target ID. Second, on the volume may be specified by the corresponding .Em mfidX device, such as .Em mfid0 . .Pp The .Nm utility supports several different groups of commands. The first group of commands provide information about the controller, the volumes it manages, and the drives it controls. The second group of commands are used to manage the physical drives attached to the controller. The third group of commands are used to manage the logical volumes managed by the controller. The fourth group of commands are used to manage the drive configuration for the controller. The fifth group of commands are used to manage controller-wide operations. .Pp The informational commands include: .Bl -tag -width indent .It Cm version Displays the version of .Nm . .It Cm show adapter Displays information about the RAID controller such as the model number. .It Cm show battery Displays information about the battery from the battery backup unit. .It Cm show config Displays the volume and drive configuration for the controller. Each array is listed along with the physical drives the array is built from. Each volume is listed along with the arrays that the volume spans. If any hot spare drives are configured, then they are listed as well. .It Cm show drives Lists all of the physical drives attached to the controller. .It Xo Cm show events .Op Fl c Ar class .Op Fl l Ar locale .Op Fl n Ar count .Op Fl v .Op Ar start Op Ar stop .Xc Display entries from the controller's event log. The controller maintains a circular buffer of events. Each event is tagged with a class and locale. .Pp The .Ar class parameter limits the output to entries at the specified class or higher. The default class is .Dq warn . The available classes from lowest priority to highest are: .Bl -tag -width -indent .It Cm debug Debug messages. .It Cm progress Periodic progress updates for long-running operations such as background initializations, array rebuilds, or patrol reads. .It Cm info Informational messages such as drive insertions and volume creations. .It Cm warn Indicates that some component may be close to failing. .It Cm crit A component has failed, but no data is lost. For example, a volume becoming degraded due to a drive failure. .It Cm fatal A component has failed resulting in data loss. .It Cm dead The controller itself has died. .El .Pp The .Ar locale parameter limits the output to entries for the specified part of the controller. The default locale is .Dq all . The available locales are .Dq volume , .Dq drive , .Dq enclosure , .Dq battery , .Dq sas , .Dq controller , .Dq config , .Dq cluster , and .Dq all . .Pp The .Ar count parameter is a debugging aid that specifies the number of events to fetch from the controller for each low-level request. The default is 15 events. .Pp By default, matching event log entries from the previous shutdown up to the present are displayed. This range can be adjusted via the .Ar start and .Ar stop parameters. Each of these parameters can either be specified as a log entry number or as one of the following aliases: .Bl -tag -width -indent .It Cm newest The newest entry in the event log. .It Cm oldest The oldest entry in the event log. .It Cm clear The first entry since the event log was cleared. .It Cm shutdown The entry in the event log corresponding to the last time the controller was cleanly shut down. .It Cm boot The entry in the event log corresponding to the most recent boot. .El .It Cm show firmware Lists all of the firmware images present on the controller. .It Cm show logstate Display the various sequence numbers associated with the event log. .It Cm show patrol Display the status of the controller's patrol read operation. .It Cm show progress Report the current progress and estimated completion time for active operations on all volumes and drives. .It Cm show volumes Lists all of the logical volumes managed by the controller. .El .Pp The physical drive management commands include: .Bl -tag -width indent .It Cm fail Ar drive Mark .Ar drive as failed. .Ar Drive must be an online drive that is part of an array. .It Cm good Ar drive Mark .Ar drive as an unconfigured good drive. .Ar Drive must not be part of an existing array. .It Cm rebuild Ar drive Mark a failed .Ar drive that is still part of an array as a good drive suitable for a rebuild. The firmware should kick off an array rebuild on its own if a failed drive is marked as a rebuild drive. .It Cm drive progress Ar drive Report the current progress and estimated completion time of drive operations such as rebuilds or patrol reads. .It Cm drive clear Ar drive Brq "start | stop" Start or stop the writing of all 0x00 characters to a drive. .It Cm start rebuild Ar drive Manually start a rebuild on .Ar drive . .It Cm abort rebuild Ar drive Abort an in-progress rebuild operation on .Ar drive . It can be resumed with the .Cm start rebuild command. .It Cm locate Ar drive Brq "on | off" Change the state of the external LED associated with .Ar drive . .El .Pp The logical volume management commands include: .Bl -tag -width indent .It Cm cache Ar volume Op Ar setting Oo Ar value Oc Op ... If no .Ar setting arguments are supplied, then the current cache policy for .Ar volume is displayed; otherwise, the cache policy for .Ar volume is modified. One or more .Ar setting arguments may be given. Some settings take an additional .Ar value argument as noted below. The valid settings are: .Bl -tag -width indent .It Cm enable Enable caching for both read and write I/O operations. .It Cm disable Disable caching for both read and write I/O operations. .It Cm reads Enable caching only for read I/O operations. .It Cm writes Enable caching only for write I/O operations. .It Cm write-back Use write-back policy for cached writes. .It Cm write-through Use write-through policy for cached writes. .It Cm read-ahead Ar value Set the read ahead policy for cached reads. The .Ar value argument can be set to either .Dq none , .Dq adaptive , or .Dq always . .It Cm bad-bbu-write-cache Ar value Control the behavior of I/O write caching if the battery is dead or missing. The .Ar value argument can be set to either .Dq disable or .Dq enable . In general this setting should be left disabled to avoid data loss when the system loses power. .It Cm write-cache Ar value Control the write caches on the physical drives backing .Ar volume . The .Ar value argument can be set to either .Dq disable , .Dq enable , or .Dq default . .Pp In general this setting should be left disabled to avoid data loss when the physical drives lose power. The battery backup of the RAID controller does not save data in the write caches of the physical drives. .El .It Cm name Ar volume Ar name Sets the name of .Ar volume to .Ar name . .It Cm volume progress Ar volume Report the current progress and estimated completion time of volume operations such as consistency checks and initializations. .El .Pp The configuration commands include: .Bl -tag -width indent .It Cm clear Delete the entire configuration including all volumes, arrays, and spares. .It Xo Cm create Ar type .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Op Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Xc Create a new volume. The .Ar type specifies the type of volume to create. Currently supported types include: .Bl -tag -width indent .It Cm jbod Creates a RAID0 volume for each drive specified. Each drive must be specified as a separate argument. .It Cm raid0 Creates one RAID0 volume spanning the drives listed in the single drive list. .It Cm raid1 Creates one RAID1 volume spanning the drives listed in the single drive list. .It Cm raid5 Creates one RAID5 volume spanning the drives listed in the single drive list. .It Cm raid6 Creates one RAID6 volume spanning the drives listed in the single drive list. .It Cm raid10 Creates one RAID10 volume spanning multiple RAID1 arrays. The drives for each RAID1 array are specified as a single drive list. .It Cm raid50 Creates one RAID50 volume spanning multiple RAID5 arrays. The drives for each RAID5 array are specified as a single drive list. .It Cm raid60 Creates one RAID60 volume spanning multiple RAID6 arrays. The drives for each RAID6 array are specified as a single drive list. .It Cm concat Creates a single volume by concatenating all of the drives in the single drive list. .El .Pp .Sy Note: Not all volume types are supported by all controllers. .Pp If the .Fl v flag is specified after .Ar type , then more verbose output will be enabled. Currently this just provides notification as drives are added to arrays and arrays to volumes when building the configuration. .Pp The .Fl s .Ar stripe_size parameter allows the stripe size of the array to be set. By default a stripe size of 64K is used. Valid values are 512 through 1M, though the MFI firmware may reject some values. .It Cm delete Ar volume Delete the volume .Ar volume . .It Cm add Ar drive Op Ar volume Mark .Ar drive as a hot spare. .Ar Drive must be in the unconfigured good state. If .Ar volume is specified, then the hot spare will be dedicated to arrays backing that volume. Otherwise, .Ar drive will be used as a global hot spare backing all arrays for this controller. Note that .Ar drive must be as large as the smallest drive in all of the arrays it is going to back. .It Cm remove Ar drive Remove the hot spare .Ar drive from service. It will be placed in the unconfigured good state. .El .Pp The controller management commands include: .Bl -tag -width indent .It Cm patrol Ar command Op Ar interval Op Ar start Set the patrol read operation mode. The .Ar command argument can be one of the following values: .Bl -tag -width indent .It Cm disable Disable patrol reads. .It Cm auto Enable periodic patrol reads initiated by the firmware. The optional .Ar interval argument specifies the interval in seconds between patrol reads. If patrol reads should be run continuously, then .Ar interval should consist of the word .Dq continuously . The optional .Ar start argument specifies a non-negative, relative start time for the next patrol read. If an interval or start time is not specified, then the existing setting will be used. .It Cm manual Enable manual patrol reads that are only initiated by the user. .El .It Cm start patrol Start a patrol read operation. .It Cm stop patrol Stop a currently running patrol read operation. .It Cm flash Ar file Updates the flash on the controller with the firmware stored in .Ar file . A reboot is required for the new firmware to take effect. .El .Sh EXAMPLES Configure the cache for volume mfid0 to cache only writes: .Pp .Dl Nm Cm cache mfid0 writes .Dl Nm Cm cache mfid0 write-back .Pp Create a RAID5 array spanning the first four disks in the second enclosure: .Pp .Dl Nm Cm create raid5 e1:s0,e1:s1,e1:s2,e1:s4 .Pp Configure the first three disks on a controller as JBOD: .Pp .Dl Nm Cm create jbod 0 1 2 .Pp Create a RAID10 volume that spans two arrays each of which contains two disks from two different enclosures: .Pp .Dl Nm Cm create raid10 e1:s0,e1:s1 e2:s0,e2:s1 .Pp Add drive with the device ID of 4 as a global hot spare: .Pp .Dl Nm Cm add 4 .Pp Add the drive in slot 2 in the main chassis as a hot spare for volume mfid0: .Pp .Dl Nm Cm add s2 mfid0 .Pp Configure the adapter to run periodic patrol reads once a week with the first patrol read starting in 5 minutes: .Pp .Dl Nm Cm patrol auto 604800 300 -.Pp .Sh SEE ALSO .Xr mfi 4 .Sh HISTORY The .Nm utility first appeared in .Fx 8.0 . diff --git a/usr.sbin/mptutil/mptutil.8 b/usr.sbin/mptutil/mptutil.8 index a5b3593f84e1..d2f35617a95e 100644 --- a/usr.sbin/mptutil/mptutil.8 +++ b/usr.sbin/mptutil/mptutil.8 @@ -1,398 +1,397 @@ .\" .\" Copyright (c) 2008 Yahoo!, Inc. .\" All rights reserved. .\" Written by: John Baldwin .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd August 16, 2009 .Dt MPTUTIL 8 .Os .Sh NAME .Nm mptutil .Nd Utility for managing LSI Fusion-MPT controllers .Sh SYNOPSIS .Nm .Cm version .Nm .Op Fl u Ar unit .Cm show adapter .Nm .Op Fl u Ar unit .Cm show config .Nm .Op Fl u Ar unit .Cm show drives .Nm .Op Fl u Ar unit .Cm show events .Nm .Op Fl u Ar unit .Cm show volumes .Nm .Op Fl u Ar unit .Cm fail Ar drive .Nm .Op Fl u Ar unit .Cm online Ar drive .Nm .Op Fl u Ar unit .Cm offline Ar drive .Nm .Op Fl u Ar unit .Cm name Ar volume Ar name .Nm .Op Fl u Ar unit .Cm volume status Ar volume .Nm .Op Fl u Ar unit .Cm volume cache Ar volume .Ar enable|disable .Nm .Op Fl u Ar unit .Cm clear .Nm .Op Fl u Ar unit .Cm create Ar type .Op Fl q .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Nm .Op Fl u Ar unit .Cm delete Ar volume .Nm .Op Fl u Ar unit .Cm add Ar drive Op Ar volume .Nm .Op Fl u Ar unit .Cm remove Ar drive .Sh DESCRIPTION The .Nm utility can be used to display or modify various parameters on LSI Fusion-MPT controllers. Each invocation of .Nm consists of zero or more global options followed by a command. Commands may support additional optional or required arguments after the command. .Pp Currently one global option is supported: .Bl -tag -width indent .It Fl u Ar unit .Ar unit specifies the unit of the controller to work with. If no unit is specified, then unit 0 is used. .El .Pp Volumes may be specified in two forms. First, a volume may be identified by its location as .Sm off .Op Ar xx Ns \&: .Ar yy .Sm on where .Ar xx is the bus ID and .Ar yy is the target ID. If the bus ID is omitted, the volume is assumed to be on bus 0. Second, on the volume may be specified by the corresponding .Em daX device, such as .Em da0 . .Pp The .Xr mpt 4 controller divides drives up into two categories. Configured drives belong to a RAID volume either as a member drive or as a hot spare. Each configured drive is assigned a unique device ID such as 0 or 1 that is show in .Cm show config , and in the first column of .Cm show drives . Any drive not associated with a RAID volume as either a member or a hot spare is a standalone drive. Standalone drives are visible to the operating system as SCSI disk devices. As a result, drives may be specified in three forms. First, a configured drive may be identified by its device ID. Second, any drive may be identified by its location as .Sm off .Ar xx Ns \&: .Ar yy .Sm on where .Ar xx is the bus ID and .Ar yy is the target ID for each drive as displayed in .Cm show drives . Note that unlike volumes, a drive location always requires the bus ID to avoid confusion with device IDs. Third, a standalone drive that is not part of a volume may be identified by its corresponding .Em daX device as displayed in .Cm show drives . .Pp The .Nm utility supports several different groups of commands. The first group of commands provide information about the controller, the volumes it manages, and the drives it controls. The second group of commands are used to manage the physical drives attached to the controller. The third group of commands are used to manage the logical volumes managed by the controller. The fourth group of commands are used to manage the drive configuration for the controller. .Pp The informational commands include: .Bl -tag -width indent .It Cm version Displays the version of .Nm . .It Cm show adapter Displays information about the RAID controller such as the model number. .It Cm show config Displays the volume and drive configuration for the controller. Each volume is listed along with the physical drives that the volume spans. If any hot spare drives are configured, then they are listed as well. .It Cm show drives Lists all of the physical drives attached to the controller. .It Cm show events Display all the entries from the controller's event log. Due to lack of documentation this command isn't very useful currently and just dumps each log entry in hex. .It Cm show volumes Lists all of the logical volumes managed by the controller. .El .Pp The physical drive management commands include: .Bl -tag -width indent .It Cm fail Ar drive Mark .Ar drive as .Dq failed requested . Note that this state is different from the .Dq failed state that is used when the firmware fails a drive. .Ar Drive must be a configured drive. .It Cm online Ar drive Mark .Ar drive as an online drive. .Ar Drive must be part a configured drive in either the .Dq offline or .Dq failed requested states. .It Cm offline Ar drive Mark .Ar drive as offline. .Ar Drive must be a configured, online drive. .El .Pp The logical volume management commands include: .Bl -tag -width indent .It Cm name Ar volume Ar name Sets the name of .Ar volume to .Ar name . .It Cm volume cache Ar volume Ar enable|disable Enables or disables the drive write cache for the member drives of .Ar volume . .It Cm volume status Ar volume Display more detailed status about a single volume including the current progress of a rebuild operation if one is being performed. .El .Pp The configuration commands include: .Bl -tag -width indent .It Cm clear Delete the entire configuration including all volumes and spares. All drives will become standalone drives. .It Xo Cm create Ar type .Op Fl q .Op Fl v .Op Fl s Ar stripe_size .Ar drive Ns Op \&, Ns Ar drive Ns Op ",..." .Xc Create a new volume. The .Ar type specifies the type of volume to create. Currently supported types include: .Bl -tag -width indent .It Cm raid0 Creates one RAID0 volume spanning the drives listed in the single drive list. .It Cm raid1 Creates one RAID1 volume spanning the drives listed in the single drive list. .It Cm raid1e Creates one RAID1E volume spanning the drives listed in the single drive list. .El .Pp .Sy Note: Not all volume types are supported by all controllers. .Pp If the .Fl q flag is specified after .Ar type , then a .Dq quick initialization of the volume will be done. This is useful when the drives do not contain any existing data that need to be preserved. .Pp If the .Fl v flag is specified after .Ar type , then more verbose output will be enabled. Currently this just provides notification as drives are added to volumes when building the configuration. .Pp The .Fl s .Ar stripe_size parameter allows the stripe size of the array to be set. By default a stripe size of 64K is used. The list of valid values for a given .Ar type are listed in the output of .Cm show adapter . .It Cm delete Ar volume Delete the volume .Ar volume . Member drives will become standalone drives. .It Cm add Ar drive Op Ar volume Mark .Ar drive as a hot spare. .Ar Drive must not be a member of a volume. If .Ar volume is specified, then the hot spare will be dedicated to that volume. Otherwise, .Ar drive will be used as a global hot spare backing all volumes for this controller. Note that .Ar drive must be as large as the smallest drive in all of the volumes it is going to back. .It Cm remove Ar drive Remove the hot spare .Ar drive from service. It will become a standalone drive. .El .Sh EXAMPLES Mark the drive at bus 0 target 4 as offline: .Pp .Dl Nm Cm offline 0:4 .Pp Create a RAID1 array from the two standalone drives .Va da1 and .Va da2 : .Pp .Dl Nm Cm create raid1 da1,da2 .Pp Mark standalone drive .Va da3 as a global hot spare: .Pp .Dl Nm Cm add da3 .Sh SEE ALSO .Xr mpt 4 .Sh HISTORY The .Nm utility first appeared in .Fx 8.0 . .Sh BUGS -.Pp The handling of spare drives appears to be unreliable. The .Xr mpt 4 firmware manages spares via spare drive .Dq pools . There are eight pools numbered 0 through 7. Each spare drive can only be assigned to a single pool. Each volume can be backed by any combination of zero or more spare pools. The .Nm utility attempts to use the following algorithm for managing spares. Global spares are always assigned to pool 0, and all volumes are always backed by pool 0. For dedicated spares, .Nm assigns one of the remaining 7 pools to each volume and assigns dedicated drives to that pool. In practice however, it seems that assigning a drive as a spare does not take effect until the box has been rebooted. Also, the firmware renumbers the spare pool assignments after a reboot which undoes the effects of the algorithm above. Simple cases such as assigning global spares seem to work ok .Pq albeit requiring a reboot to take effect but more .Dq exotic configurations may not work reliably. .Pp Drive configuration commands result in an excessive flood of messages on the console. .Pp The mpt version 1 API that is used by .Nm and .Xr mpt 4 doesn't support volumes above two terabytes. This is a limitation of the API. If you are using this adapter with volumes larger than two terabytes, use the adapter in JBOD mode. Utilize .Xr geom 8 , .Xr zfs 8 , or another software volume manager to work around this limitation. diff --git a/usr.sbin/mtest/mtest.8 b/usr.sbin/mtest/mtest.8 index 801501d040d7..dca6a5fa6eb6 100644 --- a/usr.sbin/mtest/mtest.8 +++ b/usr.sbin/mtest/mtest.8 @@ -1,175 +1,174 @@ .\" .\" Copyright (c) 2007-2009 Bruce Simpson. .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. The name of the author may not be used to endorse or promote products .\" derived from this software without specific prior written permission .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd April 29, 2009 .Dt MTEST 8 .Os .Sh NAME .Nm mtest .Nd test multicast socket operations .Sh SYNOPSIS .Nm .Sh DESCRIPTION The .Nm utility is a small program for testing multicast socket operations. .Pp It accepts the following commands, interactively, or as part of a scripted input file (useful for automated testing): .Pp .Bl -tag -width "a ifname e.e.e.e e.e.e.e" -compact -offset indent .\" .It Ic a Ar ifname Ar mac-addr Join the link-layer group address .Ar mac-addr on interface .Ar ifname . The group address should be in IEEE 802 MAC format, delimited by colon (':') characters. .It Ic d Ar ifname Ar mac-addr Leave the link-layer group address .Ar mac-addr on interface .Ar ifname . .It Ic m Ar ifname Ar 1/0 Set or reset ALLMULTI mode on interface .Ar ifname . This option is deprecated and is now a no-op. .It Ic p Ar ifname Ar 1/0 Set or reset promiscuous mode on interface .Ar ifname . .Pp .It Ic j Ar mcast-addr Ar ifname Op Ar source-addr Join the multicast address .Ar mcast-addr on the interface with name .Ar ifname . .Pp If an optional source .Ar source-addr is specified, a source-specific join will be performed; if .Nm is already joined to the multicast address, the source will be added to its filter list. .Pp .It Ic l Ar mcast-addr Ar ifname Op Ar source-addr Leave the multicast address .Ar mcast-addr on the interface with address .Ar ifname . If a source .Ar source-addr is specified, only that source will be left. .\" .It Ic i Ar mcast-addr Ar ifname Ar n Ar source-addr ... Set the socket with membership of .Ar mcast-addr on interface .Ar ifname to include filter mode, and add .Ar n sources beginning with .Ar source-addr to the inclusion filter list. .\" .It Ic e Ar mcast-addr Ar ifname Ar n Ar source-addr ... Set the socket with membership of .Ar mcast-addr on interface .Ar ifname to exclude filter mode, and add .Ar n sources beginning with .Ar source-addr to the exclusion filter list. .\" .It Ic t Ar mcast-addr Ar ifname Ar source-addr Set the socket with membership of .Ar mcast-addr on interface .Ar ifname to block traffic from source .Ar source-addr . .\" .It Ic b Ar mcast-addr Ar ifname Ar source-addr Set the socket with membership of .Ar mcast-addr on interface .Ar ifname to allow traffic from source .Ar source-addr . .\" .Pp .It Ic g Ar mcast-addr Ar ifname Ar n Print .Ar n source filter entries for .An mcast-addr on interface .An ifname . .\" .Pp .It Ic f Ar filename Read commands from the file .Ar filename . .It Ic s Ar n Sleep for .Ar n seconds. .It Ic ?\& List legal commands. .It Ic q Quit the program. .El .Sh IMPLEMENTATION NOTES For each command implemented by .Nm , the address family of each argument must be identical; it is not possible to mix IPv4 multicast memberships with IPv6, for example. .Pp To support IPv6, all commands have now changed to accept an interface name rather than an interface address. For IPv4, the program will perform a lookup of the primary IP address based on the interface name. This may fail if no primary IP address is assigned. -.Pp .Sh SEE ALSO .Rs .%A D. Thaler .%A B. Fenner .%A B. Quinn .%T "Socket Interface Extensions for Multicast Filters" .%O RFC 3678 .Re .Sh AUTHORS .An -split .An "Bruce Simpson" .An "Steve Deering" .An "Wilbert De Graaf" diff --git a/usr.sbin/mtree/mtree.5 b/usr.sbin/mtree/mtree.5 index 9d3405eaf940..92bf3f8716b5 100644 --- a/usr.sbin/mtree/mtree.5 +++ b/usr.sbin/mtree/mtree.5 @@ -1,272 +1,271 @@ .\" Copyright (c) 1989, 1990, 1993 .\" The Regents of the University of California. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 4. Neither the name of the University nor the names of its contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" From: @(#)mtree.8 8.2 (Berkeley) 12/11/93 .\" $FreeBSD$ .\" .Dd December 31, 2007 .Dt MTREE 5 .Os .Sh NAME .Nm mtree .Nd format of mtree dir hierarchy files .Sh DESCRIPTION The .Nm format is a textual format that describes a collection of filesystem objects. Such files are typically used to create or verify directory hierarchies. .Ss General Format An .Nm file consists of a series of lines, each providing information about a single filesystem object. Leading whitespace is always ignored. .Pp When encoding file or pathnames, any backslash character or character outside of the 95 printable ASCII characters must be encoded as a backslash followed by three octal digits. When reading mtree files, any appearance of a backslash followed by three octal digits should be converted into the corresponding character. .Pp Each line is interpreted independently as one of the following types: .Bl -tag -width Cm .It Signature The first line of any mtree file must begin with .Dq #mtree . If a file contains any full path entries, the first line should begin with .Dq #mtree v2.0 , otherwise, the first line should begin with .Dq #mtree v1.0 . .It Blank Blank lines are ignored. .It Comment Lines beginning with .Cm # are ignored. .It Special Lines beginning with .Cm / are special commands that influence the interpretation of later lines. .It Relative If the first whitespace-delimited word has no .Cm / characters, it is the name of a file in the current directory. Any relative entry that describes a directory changes the current directory. .It dot-dot As a special case, a relative entry with the filename .Pa .. changes the current directory to the parent directory. Options on dot-dot entries are always ignored. .It Full If the first whitespace-delimited word has a .Cm / character after the first character, it is the pathname of a file relative to the starting directory. There can be multiple full entries describing the same file. .El .Pp Some tools that process .Nm files may require that multiple lines describing the same file occur consecutively. It is not permitted for the same file to be mentioned using both a relative and a full file specification. .Ss Special commands Two special commands are currently defined: .Bl -tag -width Cm .It Cm /set This command defines default values for one or more keywords. It is followed on the same line by one or more whitespace-separated keyword definitions. These definitions apply to all following files that do not specify a value for that keyword. .It Cm /unset This command removes any default value set by a previous .Cm /set command. It is followed on the same line by one or more keywords separated by whitespace. .El .Ss Keywords After the filename, a full or relative entry consists of zero or more whitespace-separated keyword definitions. Each such definitions consists of a key from the following list immediately followed by an '=' sign and a value. Software programs reading mtree files should warn about unrecognized keywords. .Pp Currently supported keywords are as follows: .Bl -tag -width Cm .It Cm cksum The checksum of the file using the default algorithm specified by the .Xr cksum 1 utility. .It Cm contents The full pathname of a file whose contents should be compared to the contents of this file. .It Cm flags The file flags as a symbolic name. See .Xr chflags 1 for information on these names. If no flags are to be set the string .Dq none may be used to override the current default. .It Cm ignore Ignore any file hierarchy below this file. .It Cm gid The file group as a numeric value. .It Cm gname The file group as a symbolic name. .It Cm md5 The MD5 message digest of the file. .It Cm md5digest A synonym for .Cm md5 . .It Cm sha1 The .Tn FIPS 160-1 .Pq Dq Tn SHA-1 message digest of the file. .It Cm sha1digest A synonym for .Cm sha1 . .It Cm sha256 The .Tn FIPS 180-2 .Pq Dq Tn SHA-256 message digest of the file. .It Cm sha256digest A synonym for .Cm sha256 . .It Cm ripemd160digest The .Tn RIPEMD160 message digest of the file. .It Cm rmd160 A synonym for .Cm ripemd160digest . .It Cm rmd160digest A synonym for .Cm ripemd160digest . .It Cm mode The current file's permissions as a numeric (octal) or symbolic value. .It Cm nlink The number of hard links the file is expected to have. .It Cm nochange Make sure this file or directory exists but otherwise ignore all attributes. .It Cm uid The file owner as a numeric value. .It Cm uname The file owner as a symbolic name. .It Cm size The size, in bytes, of the file. .It Cm link The file the symbolic link is expected to reference. .It Cm time The last modification time of the file, in seconds and nanoseconds. The value should include a period character and exactly nine digits after the period. .It Cm type The type of the file; may be set to any one of the following: .Pp .Bl -tag -width Cm -compact .It Cm block block special device .It Cm char character special device .It Cm dir directory .It Cm fifo fifo .It Cm file regular file .It Cm link symbolic link .It Cm socket socket .El .El -.Pp .Sh SEE ALSO .Xr cksum 1 , .Xr find 1 , .Xr mtree 8 .Sh HISTORY The .Nm utility appeared in .Bx 4.3 Reno . The .Tn MD5 digest capability was added in .Fx 2.1 , in response to the widespread use of programs which can spoof .Xr cksum 1 . The .Tn SHA-1 and .Tn RIPEMD160 digests were added in .Fx 4.0 , as new attacks have demonstrated weaknesses in .Tn MD5 . The .Tn SHA-256 digest was added in .Fx 6.0 . Support for file flags was added in .Fx 4.0 , and mostly comes from .Nx . The .Dq full entry format was added by .Nx . .Sh BUGS The .Fx implementation of mtree does not currently support the .Nm 2.0 format. The requirement for a .Dq #mtree signature line is new and not yet widely implemented. diff --git a/usr.sbin/nfsd/nfsv4.4 b/usr.sbin/nfsd/nfsv4.4 index ba855d20e05f..1d206ecc1e3d 100644 --- a/usr.sbin/nfsd/nfsv4.4 +++ b/usr.sbin/nfsd/nfsv4.4 @@ -1,310 +1,308 @@ .\" Copyright (c) 2009 Rick Macklem, University of Guelph .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd May 15, 2011 .Dt NFSV4 4 .Os .Sh NAME .Nm NFSv4 .Nd NFS Version 4 Protocol .Sh DESCRIPTION The NFS client and server provides support for the .Tn NFSv4 specification; see .%T "Network File System (NFS) Version 4 Protocol RFC 3530" . The protocol is somewhat similar to NFS Version 3, but differs in significant ways. It uses a single compound RPC that concatenates operations to-gether. Each of these operations are similar to the RPCs of NFS Version 3. The operations in the compound are performed in order, until one of them fails (returns an error) and then the RPC terminates at that point. .Pp It has integrated locking support, which implies that the server is no longer stateless. As such, the .Nm server remains in recovery mode for a grace period (always greater than the lease duration the server uses) after a reboot. During this grace period, clients may recover state but not perform other open/lock state changing operations. To provide for correct recovery semantics, a small file described by .Xr stablerestart 5 is used by the server during the recovery phase. If this file is missing or empty, there is a backup copy maintained by .Xr nfsd 8 that will be used. If either file is missing, they will be created by the .Xr nfsd 8 . If both the file and the backup copy are empty, it will result in the server starting without providing a grace period for recovery. Note that recovery only occurs when the server machine is rebooted, not when the .Xr nfsd 8 are just restarted. .Pp It provides several optional features not present in NFS Version 3: .sp .Bd -literal -offset indent -compact - NFS Version 4 ACLs - Referrals, which redirect subtrees to other servers (not yet implemented) - Delegations, which allow a client to operate on a file locally .Ed .Pp The .Nm protocol does not use a separate mount protocol and assumes that the server provides a single file system tree structure, rooted at the point in the local file system tree specified by one or more .sp 1 .Bd -literal -offset indent -compact V4: [-sec=secflavors] [host(s) or net] .Ed .sp 1 line(s) in the .Xr exports 5 file. (See .Xr exports 5 for details.) The .Xr nfsd 8 allows a limited subset of operations to be performed on non-exported subtrees of the local file system, so that traversal of the tree to the exported subtrees is possible. As such, the ``'' can be in a non-exported file system. However, the entire tree that is rooted at that point must be in local file systems that are of types that can be NFS exported. Since the .Nm file system is rooted at ``'', setting this to anything other than ``/'' will result in clients being required to use different mount paths for .Nm than for NFS Version 2 or 3. Unlike NFS Version 2 and 3, Version 4 allows a client mount to span across multiple server file systems, although not all clients are capable of doing this. .Pp .Nm uses names for users and groups instead of numbers. On the wire, they take the form: .sp .Bd -literal -offset indent -compact @ .Ed .sp where ``'' is not the same as the DNS domain used for host name lookups, but is usually set to the same string. Most systems set this ``'' to the domain name part of the machine's .Xr hostname 1 by default. However, this can normally be overridden by a command line option or configuration file for the daemon used to do the name<->number mapping. Under FreeBSD, the mapping daemon is called .Xr nfsuserd 8 and has a command line option that overrides the domain component of the machine's hostname. For use of .Nm , either client or server, this daemon must be running. If this ``'' is not set correctly or the daemon is not running, ``ls -l'' will typically report a lot of ``nobody'' and ``nogroup'' ownerships. .Pp Although uid/gid numbers are no longer used in the .Nm protocol, they will still be in the RPC authentication fields when using AUTH_SYS (sec=sys), which is the default. As such, in this case both the user/group name and number spaces must be consistent between the client and server. .Pp However, if you run .Nm with RPCSEC_GSS (sec=krb5, krb5i, krb5p), only names and KerberosV tickets will go on the wire. .Sh SERVER SETUP -.Pp To set up the NFS server that supports .Nm , you will need to either set the variables in .Xr rc.conf 5 as follows: .sp .Bd -literal -offset indent -compact nfs_server_enable="YES" nfsv4_server_enable="YES" nfsuserd_enable="YES" .Ed .sp or start .Xr mountd 8 and .Xr nfsd 8 without the ``-o'' option, which would force use of the old server. The .Xr nfsuserd 8 daemon must also be running. .Pp You will also need to add at least one ``V4:'' line to the .Xr exports 5 file for .Nm to work. .Pp If the file systems you are exporting are only being accessed via .Nm there are a couple of .Xr sysctl 8 variables that you can change, which might improve performance. .Bl -tag -width Ds .It Cm vfs.nfsd.issue_delegations when set non-zero, allows the server to issue Open Delegations to clients. These delegations permit the client to manipulate the file locally on the client. Unfortunately, at this time, client use of delegations is limited, so performance gains may not be observed. This can only be enabled when the file systems being exported to .Nm clients are not being accessed locally on the server and, if being accessed via NFS Version 2 or 3 clients, these clients cannot be using the NLM. .It Cm vfs.nfsd.enable_locallocks can be set to 0 to disable acquisition of local byte range locks. Disabling local locking can only be done if neither local accesses to the exported file systems nor the NLM is operating on them. .El .sp Note that Samba server access would be considered ``local access'' for the above discussion. .Pp To build a kernel with the NFS server that supports .Nm linked into it, the .sp .Bd -literal -offset indent -compact options NFSD .Ed .sp must be specified in the kernel's .Xr config 5 file. .Sh CLIENT MOUNTS -.Pp To do an .Nm mount, specify the ``nfsv4'' option on the .Xr mount_nfs 8 command line. This will force use of the client that supports .Nm plus set ``tcp'' and .Nm . .Pp The .Xr nfsuserd 8 must be running, as above. If the .Nm server that is being mounted on supports delegations, you can start the .Xr nfscbd 8 daemon to handle client side callbacks. This will occur if .sp .Bd -literal -offset indent -compact nfsuserd_enable="YES" nfscbd_enable="YES" .Ed .sp are set in .Xr rc.conf 5 . .sp Without a functioning callback path, a server will never issue Delegations to a client. .sp By default, the callback address will be set to the IP address acquired via rtalloc() in the kernel and port# 7745. To override the default port#, a command line option for .Xr nfscbd 8 can be used. .sp To get callbacks to work when behind a NAT gateway, a port for the callback service will need to be set up on the NAT gateway and then the address of the NAT gateway (host IP plus port#) will need to be set by assigning the .Xr sysctl 8 variable vfs.nfs.callback_addr to a string of the form: .sp N.N.N.N.N.N .sp where the first 4 Ns are the host IP address and the last two are the port# in network byte order (all decimal #s in the range 0-255). .Pp To build a kernel with the client that supports .Nm linked into it, the option .sp .Bd -literal -offset indent -compact options NFSCL .Ed .sp must be specified in the kernel's .Xr config 5 file. .Pp Options can be specified for the .Xr nfsuserd 8 and .Xr nfscbd 8 daemons at boot time via the ``nfsuserd_flags'' and ``nfscbd_flags'' .Xr rc.conf 5 variables. .Sh FILES .Bl -tag -width /var/db/nfs-stablerestart.bak -compact .It Pa /var/db/nfs-stablerestart NFS V4 stable restart file .It Pa /var/db/nfs-stablerestart.bak backup copy of the file .El .Sh SEE ALSO .Xr stablerestart 5 , .Xr mountd 8 , .Xr nfscbd 8 , .Xr nfsd 8 , .Xr nfsdumpstate 8 , .Xr nfsrevoke 8 , .Xr nfsuserd 8 , .Sh BUGS At this time, there is no recall of delegations for local file system operations. As such, delegations should only be enabled for file systems that are being used solely as NFS export volumes and are not being accessed via local system calls nor services such as Samba. diff --git a/usr.sbin/ntp/doc/ntp-keygen.8 b/usr.sbin/ntp/doc/ntp-keygen.8 index 536900f6df6b..2d48301fd613 100644 --- a/usr.sbin/ntp/doc/ntp-keygen.8 +++ b/usr.sbin/ntp/doc/ntp-keygen.8 @@ -1,602 +1,601 @@ .\" .\" $FreeBSD$ .\" .Dd May 17, 2006 .Dt NTP-KEYGEN 8 .Os .Sh NAME .Nm ntp-keygen .Nd key generation program for ntpd .Sh SYNOPSIS .Nm .Op Fl deGgHIMnPT .Op Fl c Ar scheme .Op Fl i Ar name .Op Fl p Ar password .Op Fl S Op Cm RSA | DSA .Op Fl s Ar name .Op Fl v Ar nkeys .Sh DESCRIPTION This program generates cryptographic data files used by the NTPv4 authentication and identification schemes. It generates MD5 key files used in symmetric key cryptography. In addition, if the OpenSSL software library has been installed, it generates keys, certificate and identity files used in public key cryptography. These files are used for cookie encryption, digital signature and challenge/response identification algorithms compatible with the Internet standard security infrastructure. .Pp All files are in PEM-encoded printable ASCII format, so they can be embedded as MIME attachments in mail to other sites and certificate authorities. By default, files are not encrypted. The .Fl p Ar password option specifies the write password and .Fl q Ar password option the read password for previously encrypted files. The .Nm program prompts for the password if it reads an encrypted file and the password is missing or incorrect. If an encrypted file is read successfully and no write password is specified, the read password is used as the write password by default. .Pp The .Xr ntpd 8 configuration command .Ic crypto pw Ar password specifies the read password for previously encrypted files. The daemon expires on the spot if the password is missing or incorrect. For convenience, if a file has been previously encrypted, the default read password is the name of the host running the program. If the previous write password is specified as the host name, these files can be read by that host with no explicit password. .Pp File names begin with the prefix .Cm ntpkey_ and end with the postfix .Ar _hostname.filestamp , where .Ar hostname is the owner name, usually the string returned by the Unix gethostname() routine, and .Ar filestamp is the NTP seconds when the file was generated, in decimal digits. This both guarantees uniqueness and simplifies maintenance procedures, since all files can be quickly removed by a .Ic rm ntpkey\&* command or all files generated at a specific time can be removed by a .Ic rm .Ar \&*filestamp command. To further reduce the risk of misconfiguration, the first two lines of a file contain the file name and generation date and time as comments. .Pp All files are installed by default in the keys directory .Pa /usr/local/etc , which is normally in a shared filesystem in NFS-mounted networks. The actual location of the keys directory and each file can be overridden by configuration commands, but this is not recommended. Normally, the files for each host are generated by that host and used only by that host, although exceptions exist as noted later on this page. .Pp Normally, files containing private values, including the host key, sign key and identification parameters, are permitted root read/write-only; while others containing public values are permitted world readable. Alternatively, files containing private values can be encrypted and these files permitted world readable, which simplifies maintenance in shared file systems. Since uniqueness is insured by the hostname and file name extensions, the files for a NFS server and dependent clients can all be installed in the same shared directory. .Pp The recommended practice is to keep the file name extensions when installing a file and to install a soft link from the generic names specified elsewhere on this page to the generated files. This allows new file generations to be activated simply by changing the link. If a link is present, ntpd follows it to the file name to extract the filestamp. If a link is not present, .Xr ntpd 8 extracts the filestamp from the file itself. This allows clients to verify that the file and generation times are always current. The .Nm program uses the same timestamp extension for all files generated at one time, so each generation is distinct and can be readily recognized in monitoring data. .Ss Running the program The safest way to run the .Nm program is logged in directly as root. The recommended procedure is change to the keys directory, usually .Pa /usr/local/etc , then run the program. When run for the first time, or if all .Cm ntpkey files have been removed, the program generates a RSA host key file and matching RSA-MD5 certificate file, which is all that is necessary in many cases. The program also generates soft links from the generic names to the respective files. If run again, the program uses the same host key file, but generates a new certificate file and link. .Pp The host key is used to encrypt the cookie when required and so must be RSA type. By default, the host key is also the sign key used to encrypt signatures. When necessary, a different sign key can be specified and this can be either RSA or DSA type. By default, the message digest type is MD5, but any combination of sign key type and message digest type supported by the OpenSSL library can be specified, including those using the MD2, MD5, SHA, SHA1, MDC2 and RIPE160 message digest algorithms. However, the scheme specified in the certificate must be compatible with the sign key. Certificates using any digest algorithm are compatible with RSA sign keys; however, only SHA and SHA1 certificates are compatible with DSA sign keys. .Pp Private/public key files and certificates are compatible with other OpenSSL applications and very likely other libraries as well. Certificates or certificate requests derived from them should be compatible with extant industry practice, although some users might find the interpretation of X509v3 extension fields somewhat liberal. However, the identification parameter files, although encoded as the other files, are probably not compatible with anything other than Autokey. .Pp Running the program as other than root and using the Unix .Ic su command to assume root may not work properly, since by default the OpenSSL library looks for the random seed file .Cm .rnd in the user home directory. However, there should be only one .Cm .rnd , most conveniently in the root directory, so it is convenient to define the .Cm $RANDFILE environment variable used by the OpenSSL library as the path to .Cm /.rnd . .Pp Installing the keys as root might not work in NFS-mounted shared file systems, as NFS clients may not be able to write to the shared keys directory, even as root. In this case, NFS clients can specify the files in another directory such as .Pa /etc using the .Ic keysdir command. There is no need for one client to read the keys and certificates of other clients or servers, as these data are obtained automatically by the Autokey protocol. .Pp Ordinarily, cryptographic files are generated by the host that uses them, but it is possible for a trusted agent (TA) to generate these files for other hosts; however, in such cases files should always be encrypted. The subject name and trusted name default to the hostname of the host generating the files, but can be changed by command line options. It is convenient to designate the owner name and trusted name as the subject and issuer fields, respectively, of the certificate. The owner name is also used for the host and sign key files, while the trusted name is used for the identity files. -.Pp .Ss Trusted Hosts and Groups Each cryptographic configuration involves selection of a signature scheme and identification scheme, called a cryptotype, as explained in the .Sx Authentication Options section of .Xr ntp.conf 5 . The default cryptotype uses RSA encryption, MD5 message digest and TC identification. First, configure a NTP subnet including one or more low-stratum trusted hosts from which all other hosts derive synchronization directly or indirectly. Trusted hosts have trusted certificates; all other hosts have nontrusted certificates. These hosts will automatically and dynamically build authoritative certificate trails to one or more trusted hosts. A trusted group is the set of all hosts that have, directly or indirectly, a certificate trail ending at a trusted host. The trail is defined by static configuration file entries or dynamic means described on the .Sx Automatic NTP Configuration Options section of .Xr ntp.conf 5 . .Pp On each trusted host as root, change to the keys directory. To insure a fresh fileset, remove all .Cm ntpkey files. Then run .Nm .Fl T to generate keys and a trusted certificate. On all other hosts do the same, but leave off the .Fl T flag to generate keys and nontrusted certificates. When complete, start the NTP daemons beginning at the lowest stratum and working up the tree. It may take some time for Autokey to instantiate the certificate trails throughout the subnet, but setting up the environment is completely automatic. .Pp If it is necessary to use a different sign key or different digest/signature scheme than the default, run .Nm with the .Fl S Ar type option, where .Ar type is either .Cm RSA or .Cm DSA . The most often need to do this is when a DSA-signed certificate is used. If it is necessary to use a different certificate scheme than the default, run .Nm with the .Fl c Ar scheme option and selected .Ar scheme as needed. If .Nm is run again without these options, it generates a new certificate using the same scheme and sign key. .Pp After setting up the environment it is advisable to update certificates from time to time, if only to extend the validity interval. Simply run .Nm with the same flags as before to generate new certificates using existing keys. However, if the host or sign key is changed, .Xr ntpd 8 should be restarted. When .Xr ntpd 8 is restarted, it loads any new files and restarts the protocol. Other dependent hosts will continue as usual until signatures are refreshed, at which time the protocol is restarted. .Ss Identity Schemes As mentioned on the Autonomous Authentication page, the default TC identity scheme is vulnerable to a middleman attack. However, there are more secure identity schemes available, including PC, IFF, GQ and MV described on the .Qq Identification Schemes page (maybe available at .Li http://www.eecis.udel.edu/%7emills/keygen.html ) . These schemes are based on a TA, one or more trusted hosts and some number of nontrusted hosts. Trusted hosts prove identity using values provided by the TA, while the remaining hosts prove identity using values provided by a trusted host and certificate trails that end on that host. The name of a trusted host is also the name of its sugroup and also the subject and issuer name on its trusted certificate. The TA is not necessarily a trusted host in this sense, but often is. .Pp In some schemes there are separate keys for servers and clients. A server can also be a client of another server, but a client can never be a server for another client. In general, trusted hosts and nontrusted hosts that operate as both server and client have parameter files that contain both server and client keys. Hosts that operate only as clients have key files that contain only client keys. .Pp The PC scheme supports only one trusted host in the group. On trusted host alice run .Nm .Fl P .Fl p Ar password to generate the host key file .Pa ntpkey_RSAkey_ Ns Ar alice.filestamp and trusted private certificate file .Pa ntpkey_RSA-MD5_cert_ Ns Ar alice.filestamp . Copy both files to all group hosts; they replace the files which would be generated in other schemes. On each host bob install a soft link from the generic name .Pa ntpkey_host_ Ns Ar bob to the host key file and soft link .Pa ntpkey_cert_ Ns Ar bob to the private certificate file. Note the generic links are on bob, but point to files generated by trusted host alice. In this scheme it is not possible to refresh either the keys or certificates without copying them to all other hosts in the group. .Pp For the IFF scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host alice run .Nm .Fl T .Fl I .Fl p Ar password to produce her parameter file .Pa ntpkey_IFFpar_ Ns Ar alice.filestamp , which includes both server and client keys. Copy this file to all group hosts that operate as both servers and clients and install a soft link from the generic .Pa ntpkey_iff_ Ns Ar alice to this file. If there are no hosts restricted to operate only as clients, there is nothing further to do. As the IFF scheme is independent of keys and certificates, these files can be refreshed as needed. .Pp If a rogue client has the parameter file, it could masquerade as a legitimate server and present a middleman threat. To eliminate this threat, the client keys can be extracted from the parameter file and distributed to all restricted clients. After generating the parameter file, on alice run .Nm .Fl e and pipe the output to a file or mail program. Copy or mail this file to all restricted clients. On these clients install a soft link from the generic .Pa ntpkey_iff_ Ns Ar alice to this file. To further protect the integrity of the keys, each file can be encrypted with a secret password. .Pp For the GQ scheme proceed as in the TC scheme to generate keys and certificates for all group hosts, then for every trusted host in the group, generate the IFF parameter file. On trusted host alice run .Nm .Fl T .Fl G .Fl p Ar password to produce her parameter file .Pa ntpkey_GQpar_ Ns Ar alice.filestamp , which includes both server and client keys. Copy this file to all group hosts and install a soft link from the generic .Pa ntpkey_gq_ Ns Ar alice to this file. In addition, on each host bob install a soft link from generic .Pa ntpkey_gq_ Ns Ar bob to this file. As the GQ scheme updates the GQ parameters file and certificate at the same time, keys and certificates can be regenerated as needed. .Pp For the MV scheme, proceed as in the TC scheme to generate keys and certificates for all group hosts. For illustration assume trish is the TA, alice one of several trusted hosts and bob one of her clients. On TA trish run .Nm .Fl V Ar n .Fl p Ar password , where .Ar n is the number of revokable keys (typically 5) to produce the parameter file .Pa ntpkeys_MVpar_ Ns Ar trish.filestamp and client key files .Pa ntpkeys_MVkeyd_ Ns Ar trish.filestamp where .Ar d is the key number (0 \&< .Ar d \&< .Ar n ) . Copy the parameter file to alice and install a soft link from the generic .Pa ntpkey_mv_ Ns Ar alice to this file. Copy one of the client key files to alice for later distribution to her clients. It doesn't matter which client key file goes to alice, since they all work the same way. Alice copies the client key file to all of her cliens. On client bob install a soft link from generic .Pa ntpkey_mvkey_ Ns Ar bob to the client key file. As the MV scheme is independent of keys and certificates, these files can be refreshed as needed. .Ss Command Line Options .Bl -tag -width indent .It Fl c Ar scheme Select certificate message digest/signature encryption scheme. The .Ar scheme can be one of the following: . Cm RSA-MD2 , RSA-MD5 , RSA-SHA , RSA-SHA1 , RSA-MDC2 , RSA-RIPEMD160 , DSA-SHA , or .Cm DSA-SHA1 . Note that RSA schemes must be used with a RSA sign key and DSA schemes must be used with a DSA sign key. The default without this option is .Cm RSA-MD5 . .It Fl d Enable debugging. This option displays the cryptographic data produced in eye-friendly billboards. .It Fl e Write the IFF client keys to the standard output. This is intended for automatic key distribution by mail. .It Fl G Generate parameters and keys for the GQ identification scheme, obsoleting any that may exist. .It Fl g Generate keys for the GQ identification scheme using the existing GQ parameters. If the GQ parameters do not yet exist, create them first. .It Fl H Generate new host keys, obsoleting any that may exist. .It Fl I Generate parameters for the IFF identification scheme, obsoleting any that may exist. .It Fl i Ar name Set the suject name to .Ar name . This is used as the subject field in certificates and in the file name for host and sign keys. .It Fl M Generate MD5 keys, obsoleting any that may exist. .It Fl P Generate a private certificate. By default, the program generates public certificates. .It Fl p Ar password Encrypt generated files containing private data with .Ar password and the DES-CBC algorithm. .It Fl q Set the password for reading files to password. .It Fl S Oo Cm RSA | DSA Oc Generate a new sign key of the designated type, obsoleting any that may exist. By default, the program uses the host key as the sign key. .It Fl s Ar name Set the issuer name to .Ar name . This is used for the issuer field in certificates and in the file name for identity files. .It Fl T Generate a trusted certificate. By default, the program generates a non-trusted certificate. .It Fl V Ar nkeys Generate parameters and keys for the Mu-Varadharajan (MV) identification scheme. .El .Ss Random Seed File All cryptographically sound key generation schemes must have means to randomize the entropy seed used to initialize the internal pseudo-random number generator used by the library routines. The OpenSSL library uses a designated random seed file for this purpose. The file must be available when starting the NTP daemon and .Nm program. If a site supports OpenSSL or its companion OpenSSH, it is very likely that means to do this are already available. .Pp It is important to understand that entropy must be evolved for each generation, for otherwise the random number sequence would be predictable. Various means dependent on external events, such as keystroke intervals, can be used to do this and some systems have built-in entropy sources. Suitable means are described in the OpenSSL software documentation, but are outside the scope of this page. .Pp The entropy seed used by the OpenSSL library is contained in a file, usually called .Cm .rnd , which must be available when starting the NTP daemon or the .Nm program. The NTP daemon will first look for the file using the path specified by the .Ic randfile subcommand of the .Ic crypto configuration command. If not specified in this way, or when starting the .Nm program, the OpenSSL library will look for the file using the path specified by the .Ev RANDFILE environment variable in the user home directory, whether root or some other user. If the .Ev RANDFILE environment variable is not present, the library will look for the .Cm .rnd file in the user home directory. If the file is not available or cannot be written, the daemon exits with a message to the system log and the program exits with a suitable error message. .Ss Cryptographic Data Files All other file formats begin with two lines. The first contains the file name, including the generated host name and filestamp. The second contains the datestamp in conventional Unix date format. Lines beginning with # are considered comments and ignored by the .Nm program and .Xr ntpd 8 daemon. Cryptographic values are encoded first using ASN.1 rules, then encrypted if necessary, and finally written PEM-encoded printable ASCII format preceded and followed by MIME content identifier lines. .Pp The format of the symmetric keys file is somewhat different than the other files in the interest of backward compatibility. Since DES-CBC is deprecated in NTPv4, the only key format of interest is MD5 alphanumeric strings. Following hte heard the keys are entered one per line in the format .D1 Ar keyno type key where .Ar keyno is a positive integer in the range 1-65,535, .Ar type is the string MD5 defining the key format and .Ar key is the key itself, which is a printable ASCII string 16 characters or less in length. Each character is chosen from the 93 printable characters in the range 0x21 through 0x7f excluding space and the .Ql # character. .Pp Note that the keys used by the .Xr ntpq 8 and .Xr ntpdc 8 programs are checked against passwords requested by the programs and entered by hand, so it is generally appropriate to specify these keys in human readable ASCII format. .Pp The .Nm program generates a MD5 symmetric keys file .Pa ntpkey_MD5key_ Ns Ar hostname.filestamp . Since the file contains private shared keys, it should be visible only to root and distributed by secure means to other subnet hosts. The NTP daemon loads the file .Pa ntp.keys , so .Nm installs a soft link from this name to the generated file. Subsequently, similar soft links must be installed by manual or automated means on the other subnet hosts. While this file is not used with the Autokey Version 2 protocol, it is needed to authenticate some remote configuration commands used by the .Xr ntpq 8 and .Xr ntpdc 8 utilities. .Sh Bugs It can take quite a while to generate some cryptographic values, from one to several minutes with modern architectures such as UltraSPARC and up to tens of minutes to an hour with older architectures such as SPARC IPC. diff --git a/usr.sbin/ntp/doc/ntpdate.8 b/usr.sbin/ntp/doc/ntpdate.8 index f361f17133af..e5aaecd4329e 100644 --- a/usr.sbin/ntp/doc/ntpdate.8 +++ b/usr.sbin/ntp/doc/ntpdate.8 @@ -1,280 +1,279 @@ .\" .\" $FreeBSD$ .\" .Dd May 17, 2006 .Dt NTPDATE 8 .Os .Sh NAME .Nm ntpdate .Nd set the date and time via NTP .Sh SYNOPSIS .Nm .Op Fl 46bBdoqsuv .Op Fl a Ar key .Op Fl e Ar authdelay .Op Fl k Ar keyfile .Op Fl o Ar version .Op Fl p Ar samples .Op Fl t Ar timeout .Ar server ... .Sh DESCRIPTION -.Pp .Em Note : The functionality of this program is now available in the .Xr ntpd 8 program. See the .Fl q command line option in the .Xr ntpd 8 page. After a suitable period of mourning, the .Nm utility is to be retired from this distribution. .Pp The .Nm utility sets the local date and time by polling the Network Time Protocol (NTP) server(s) given as the .Ar server arguments to determine the correct time. It must be run as root on the local host. A number of samples are obtained from each of the servers specified and a subset of the NTP clock filter and selection algorithms are applied to select the best of these. Note that the accuracy and reliability of .Nm depends on the number of servers, the number of polls each time it is run and the interval between runs. .Pp The following options are available: .Bl -tag -width indent .It Fl 4 Force DNS resolution of following host names on the command line to the IPv4 namespace. .It Fl 6 Force DNS resolution of following host names on the command line to the IPv6 namespace. .It Fl a Ar key Enable the authentication function and specify the key identifier to be used for authentication as the argument .Ar key . The keys and key identifiers must match in both the client and server key files. The default is to disable the authentication function. .It Fl B Force the time to always be slewed using the .Xr adjtime 2 system call, even if the measured offset is greater than +-128 ms. The default is to step the time using .Xr settimeofday 2 if the offset is greater than +-128 ms. Note that, if the offset is much greater than +-128 ms in this case, it can take a long time (hours) to slew the clock to the correct value. During this time, the host should not be used to synchronize clients. .It Fl b Force the time to be stepped using the .Xr settimeofday 2 system call, rather than slewed (default) using the .Xr adjtime 2 system call. This option should be used when called from a startup file at boot time. .It Fl d Enable the debugging mode, in which .Nm will go through all the steps, but not adjust the local clock. Information useful for general debugging will also be printed. .It Fl e Ar authdelay Specify the processing delay to perform an authentication function as the value .Ar authdelay , in seconds and fraction (see .Xr ntpd 8 for details). This number is usually small enough to be negligible for most purposes, though specifying a value may improve timekeeping on very slow CPU's. .It Fl k Ar keyfile Specify the path for the authentication key file as the string .Ar keyfile . The default is .Pa /etc/ntp.keys . This file should be in the format described in .Xr ntpd 8 . .It Fl o Ar version Specify the NTP version for outgoing packets as the integer .Ar version , which can be 1 or 2. The default is 3. This allows .Nm to be used with older NTP versions. .It Fl p Ar samples Specify the number of samples to be acquired from each server as the integer .Ar samples , with values from 1 to 8 inclusive. The default is 4. .It Fl q Query only - do not set the clock. .It Fl s Divert logging output from the standard output (default) to the system .Xr syslog 3 facility. This is designed primarily for convenience of .Xr cron 8 scripts. .It Fl t Ar timeout Specify the maximum time waiting for a server response as the value .Ar timeout , in seconds and fraction. The value is rounded to a multiple of 0.2 seconds. The default is 1 second, a value suitable for polling across a LAN. .It Fl u Direct .Nm to use an unprivileged port for outgoing packets. This is most useful when behind a firewall that blocks incoming traffic to privileged ports, and you want to synchronise with hosts beyond the firewall. Note that the .Fl d option always uses unprivileged ports. .It Fl v Be verbose. This option will cause .Nm Ns 's version identification string to be logged. .El .Pp The .Nm utility can be run manually as necessary to set the host clock, or it can be run from the host startup script to set the clock at boot time. This is useful in some cases to set the clock initially before starting the NTP daemon .Xr ntpd 8 . It is also possible to run .Nm from a .Xr cron 8 script. However, it is important to note that .Nm with contrived .Xr cron 8 scripts is no substitute for the NTP daemon, which uses sophisticated algorithms to maximize accuracy and reliability while minimizing resource use. Finally, since .Nm does not discipline the host clock frequency as does .Xr ntpd 8 , the accuracy using .Nm is limited. .Pp Time adjustments are made by .Nm in one of two ways. If .Nm determines the clock is in error more than 0.5 second it will simply step the time by calling the system .Xr settimeofday 2 routine. If the error is less than 0.5 seconds, it will slew the time by calling the system .Xr adjtime 2 routine. The latter technique is less disruptive and more accurate when the error is small, and works quite well when .Nm is run by .Xr cron 8 every hour or two. .Pp The .Nm utility will decline to set the date if an NTP server daemon (e.g., .Xr ntpd 8 ) is running on the same host. When running .Nm on a regular basis from .Xr cron 8 as an alternative to running a daemon, doing so once every hour or two will result in precise enough timekeeping to avoid stepping the clock. .Pp Note that in contexts where a host name is expected, a .Fl 4 qualifier preceding the host name forces DNS resolution to the IPv4 namespace, while a .Fl 6 qualifier forces DNS resolution to the IPv6 namespace. .Pp If NetInfo support is compiled into .Nm , then the .Cm server argument is optional if .Nm can find a time server in the NetInfo configuration for .Xr ntpd 8 . .Sh FILES .Bl -tag -width /etc/ntp.keys -compact .It Pa /etc/ntp.keys contains the encryption keys used by .Nm . .El .Sh SEE ALSO .Xr ntpd 8 .Sh BUGS The slew adjustment is actually 50% larger than the measured offset, since this (it is argued) will tend to keep a badly drifting clock more accurate. This is probably not a good idea and may cause a troubling hunt for some values of the kernel variables .Va kern.clockrate.tick and .Va kern.clockrate.tickadj . diff --git a/usr.sbin/utx/utx.8 b/usr.sbin/utx/utx.8 index d4e043989720..6154dca3bef7 100644 --- a/usr.sbin/utx/utx.8 +++ b/usr.sbin/utx/utx.8 @@ -1,107 +1,106 @@ .\" Copyright (c) 2011-2012 Ed Schouten .\" All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd February 11, 2012 .Dt UTX 8 .Os .Sh NAME .Nm utx , .Nm utxrm .Nd manage the user accounting database .Sh SYNOPSIS .Nm .Cm boot .Nm .Cm shutdown .Nm .Cm rm .Ar identifier .Ar ... .Nm utxrm .Ar identifier .Ar ... .Sh DESCRIPTION The .Nm utility can be used to perform operations on the user accounting database, as done by .Xr pututxline 3 . .Pp The first argument to .Nm indicates an action to be performed: .Bl -tag -width ".Cm shutdown" .It Cm boot Write a boot time record to the user accounting database. This option should typically only be used by .Xr rc 8 . .It Cm shutdown Write a shutdown time record to the user accounting database. This option should typically only be used by .Xr rc 8 . .It Cm rm Remove stale sessions from the user accounting database, by referring to their .Ar identifier . Stale sessions can occur if a login service exits prematurely or fails to remove the session from the accounting database. .Pp Utilities such as .Xr w 1 will not display the identifier corresponding with a login session, since its value is typically only of use by the process managing the record. The following command can be used to obtain all records from the user accounting database's active session table, including its identifiers: .Pp .Dl getent utmpx active .Pp Identifiers can either be supplied in hexadecimal form as displayed by .Xr getent 1 , or as a string if the identifier allows such a representation. .Pp To remain backward compatible, this action can also be invoked directly by using the .Nm utxrm command. .El .Pp -.Pp Because this utility requires write-access to the user accounting database, its use is limited to the super-user. .Sh SEE ALSO .Xr getent 1 , .Xr w 1 , .Xr pututxline 3 . .Sh HISTORY The .Nm utility replaced .Nm utxrm in .Fx 10.0 . .Sh AUTHORS .An Ed Schouten Aq ed@FreeBSD.org diff --git a/usr.sbin/ypserv/ypserv.8 b/usr.sbin/ypserv/ypserv.8 index 9d88731bab0d..b212c49805c0 100644 --- a/usr.sbin/ypserv/ypserv.8 +++ b/usr.sbin/ypserv/ypserv.8 @@ -1,465 +1,463 @@ .\" Copyright (c) 1995 .\" Bill Paul . All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without .\" modification, are permitted provided that the following conditions .\" are met: .\" 1. Redistributions of source code must retain the above copyright .\" notice, this list of conditions and the following disclaimer. .\" 2. Redistributions in binary form must reproduce the above copyright .\" notice, this list of conditions and the following disclaimer in the .\" documentation and/or other materials provided with the distribution. .\" 3. All advertising materials mentioning features or use of this software .\" must display the following acknowledgement: .\" This product includes software developed by Bill Paul. .\" 4. Neither the name of the author nor the names of any co-contributors .\" may be used to endorse or promote products derived from this software .\" without specific prior written permission. .\" .\" THIS SOFTWARE IS PROVIDED BY Bill Paul AND CONTRIBUTORS ``AS IS'' AND .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE .\" ARE DISCLAIMED. IN NO EVENT SHALL Bill Paul OR CONTRIBUTORS BE LIABLE .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF .\" SUCH DAMAGE. .\" .\" $FreeBSD$ .\" .Dd December 13, 2009 .Dt YPSERV 8 .Os .Sh NAME .Nm ypserv .Nd NIS database server .Sh SYNOPSIS .Nm .Op Fl n .Op Fl d .Op Fl P Ar port .Op Fl p Ar path .Sh DESCRIPTION .Tn NIS is an RPC-based service designed to allow a number of UNIX-based machines to share a common set of configuration files. Rather than requiring a system administrator to update several copies of files such as .Pa /etc/hosts , .Pa /etc/passwd and .Pa /etc/group , which tend to require frequent changes in most environments, .Tn NIS allows groups of computers to share one set of data which can be updated from a single location. .Pp The .Nm utility is the server that distributes .Tn NIS databases to client systems within an .Tn NIS .Em domain . Each client in an .Tn NIS domain must have its domainname set to one of the domains served by .Nm using the .Xr domainname 1 command. The clients must also run .Xr ypbind 8 in order to attach to a particular server, since it is possible to have several servers within a single .Tn NIS domain. .Pp The databases distributed by .Nm are stored in .Pa /var/yp/[domainname] where .Pa domainname is the name of the domain being served. There can be several such directories with different domainnames, and you need only one .Nm daemon to handle them all. .Pp The databases, or .Pa maps as they are often called, are created by .Pa /var/yp/Makefile using several system files as source. The database files are in .Xr db 3 format to help speed retrieval when there are many records involved. In .Fx , the maps are always readable and writable only by root for security reasons. Technically this is only necessary for the password maps, but since the data in the other maps can be found in other world-readable files anyway, it does not hurt and it is considered good general practice. .Pp The .Nm utility is started by .Pa /etc/rc.d/ypserv if it has been enabled in .Pa /etc/rc.conf . .Sh SPECIAL FEATURES There are some problems associated with distributing a .Fx password database via .Tn NIS : .Fx normally only stores encrypted passwords in .Pa /etc/master.passwd , which is readable and writable only by root. By turning this file into an .Tn NIS map, this security feature would be completely defeated. .Pp To make up for this, the .Fx version of .Nm handles the .Pa master.passwd.byname and .Pa master.passwd.byuid maps in a special way. When the server receives a request to access either of these two maps (or in fact either of the .Pa shadow.byname or .Pa shadow.byuid maps), it will check the TCP port from which the request originated and return an error if the port number is greater than 1023. Since only the superuser is allowed to bind to TCP ports with values less than 1024, the server can use this test to determine whether or not the access request came from a privileged user. Any requests made by non-privileged users are therefore rejected. .Pp Furthermore, the .Xr getpwent 3 routines in the .Fx standard C library will only attempt to retrieve data from the .Pa master.passwd.byname and .Pa master.passwd.byuid maps for the superuser: if a normal user calls any of these functions, the standard .Pa passwd.byname and .Pa passwd.byuid maps will be accessed instead. The latter two maps are constructed by .Pa /var/yp/Makefile by parsing the .Pa master.passwd file and stripping out the password fields, and are therefore safe to pass on to unprivileged users. In this way, the shadow password aspect of the protected .Pa master.passwd database is maintained through .Tn NIS . .Sh NOTES .Ss Setting Up Master and Slave Servers .Xr ypinit 8 is a convenient script that will help setup master and slave .Tn NIS servers. .Ss Limitations There are two problems inherent with password shadowing in .Tn NIS that users should be aware of: .Bl -enum -offset indent .It The .Sq TCP port less than 1024 test is trivial to defeat for users with unrestricted access to machines on your network (even those machines which do not run UNIX-based operating systems). .It If you plan to use a .Fx system to serve .No non- Ns Fx clients that have no support for password shadowing (which is most of them), you will have to disable the password shadowing entirely by uncommenting the .Em UNSECURE=True entry in .Pa /var/yp/Makefile . This will cause the standard .Pa passwd.byname and .Pa passwd.byuid maps to be generated with valid encrypted password fields, which is necessary in order for .No non- Ns Fx clients to perform user authentication through .Tn NIS . .El -.Pp .Ss Security In general, any remote user can issue an RPC to .Nm and retrieve the contents of your .Tn NIS maps, provided the remote user knows your domain name. To prevent such unauthorized transactions, .Nm supports a feature called .Pa securenets which can be used to restrict access to a given set of hosts. At startup, .Nm will attempt to load the securenets information from a file called .Pa /var/yp/securenets . (Note that this path varies depending on the path specified with the .Fl p option, which is explained below.) This file contains entries that consist of a network specification and a network mask separated by white space. Lines starting with .Dq \&# are considered to be comments. A sample securenets file might look like this: .Bd -unfilled -offset indent # allow connections from local host -- mandatory 127.0.0.1 255.255.255.255 # allow connections from any host # on the 192.168.128.0 network 192.168.128.0 255.255.255.0 # allow connections from any host # between 10.0.0.0 to 10.0.15.255 10.0.0.0 255.255.240.0 .Ed .Pp If .Nm receives a request from an address that matches one of these rules, it will process the request normally. If the address fails to match a rule, the request will be ignored and a warning message will be logged. If the .Pa /var/yp/securenets file does not exist, .Nm will allow connections from any host. .Pp The .Nm utility also has support for Wietse Venema's .Em tcpwrapper package. This allows the administrator to use the tcpwrapper configuration files .Pa ( /etc/hosts.allow and .Pa /etc/hosts.deny ) for access control instead of .Pa /var/yp/securenets . .Pp Note: while both of these access control mechanisms provide some security, they, like the privileged port test, are both vulnerable to .Dq IP spoofing attacks. -.Pp .Ss NIS v1 compatibility This version of .Nm has some support for serving .Tn NIS v1 clients. The .Fx .Tn NIS implementation only uses the .Tn NIS v2 protocol, however other implementations include support for the v1 protocol for backwards compatibility with older systems. The .Xr ypbind 8 daemons supplied with these systems will try to establish a binding to an .Tn NIS v1 server even though they may never actually need it (and they may persist in broadcasting in search of one even after they receive a response from a v2 server). Note that while support for normal client calls is provided, this version of .Nm does not handle v1 map transfer requests; consequently, it cannot be used as a master or slave in conjunction with older .Tn NIS servers that only support the v1 protocol. Fortunately, there probably are not any such servers still in use today. .Ss NIS servers that are also NIS clients Care must be taken when running .Nm in a multi-server domain where the server machines are also .Tn NIS clients. It is generally a good idea to force the servers to bind to themselves rather than allowing them to broadcast bind requests and possibly become bound to each other: strange failure modes can result if one server goes down and others are dependent upon on it. (Eventually all the clients will time out and attempt to bind to other servers, but the delay involved can be considerable and the failure mode is still present since the servers might bind to each other all over again). .Pp Refer to the .Xr ypbind 8 man page for details on how to force it to bind to a particular server. .Sh OPTIONS The following options are supported by .Nm : .Bl -tag -width flag .It Fl n This option affects the way .Nm handles yp_match requests for the .Pa hosts.byname and .Pa hosts.byaddress maps. By default, if .Nm cannot find an entry for a given host in its hosts maps, it will return an error and perform no further processing. With the .Fl n flag, .Nm will go one step further: rather than giving up immediately, it will try to resolve the hostname or address using a DNS nameserver query. If the query is successful, .Nm will construct a fake database record and return it to the client, thereby making it seem as though the client's yp_match request succeeded. .Pp This feature is provided for compatibility with SunOS 4.1.x, which has brain-damaged resolver functions in its standard C library that depend on .Tn NIS for hostname and address resolution. The .Fx resolver can be configured to do DNS queries directly, therefore it is not necessary to enable this option when serving only .Fx .Tn NIS clients. .It Fl d Cause the server to run in debugging mode. Normally, .Nm reports only unusual errors (access violations, file access failures) using the .Xr syslog 3 facility. In debug mode, the server does not background itself and prints extra status messages to stderr for each request that it receives. Also, while running in debug mode, .Nm will not spawn any additional subprocesses as it normally does when handling yp_all requests or doing DNS lookups. (These actions often take a fair amount of time to complete and are therefore handled in subprocesses, allowing the parent server process to go on handling other requests.) This makes it easier to trace the server with a debugging tool. .It Fl h Ar addr Specify a specific address to bind to for requests. This option may be specified multiple times. If no .Fl h option is specified, .Nm will bind to default passive address .Pq e.g. INADDR_ANY for IPv4 for each transport. .It Fl P Ar port Force ypserv to bind to a specific TCP/UDP port, rather than selecting its own. .It Fl p Ar path Normally, .Nm assumes that all .Tn NIS maps are stored under .Pa /var/yp . The .Fl p flag may be used to specify an alternate .Tn NIS root path, allowing the system administrator to move the map files to a different place within the file system. .El .Sh FILES .Bl -tag -width Pa -compact .It Pa /var/yp/[domainname]/[maps] the .Tn NIS maps .It Pa /etc/nsswitch.conf name switch configuration file .It Pa /var/yp/securenets host access control file .El .Sh SEE ALSO .Xr ypcat 1 , .Xr db 3 , .Xr hosts_access 5 , .Xr rpc.yppasswdd 8 , .Xr yp 8 , .Xr ypbind 8 , .Xr ypinit 8 , .Xr yppush 8 , .Xr ypxfr 8 .Sh HISTORY This version of .Nm first appeared in .Fx 2.2 . .Sh AUTHORS .An Bill Paul Aq wpaul@ctr.columbia.edu