From 41288eb5e4594aa90a11515500df2e74650f1522 Mon Sep 17 00:00:00 2001 From: Zdenek Styblik Date: Mon, 8 Jul 2013 08:29:20 +0000 Subject: [PATCH] ID: 161 - documentation Commit contains following documentation changes and related code usage changes: * sorted arguments * sorted command line commands * adds missing arguments * adds hidden aliases arguments with note of deprecation (feel free to remove if not deprecated) * fixes incomplete synopsis * restructures synopsis to logical blocks * conditional argument and command combination overrides to fixed defaults Commit for Ales Ledvinka --- ipmitool/doc/ipmitool.1 | 1740 +++++++++++++++++++++++---------------- 1 file changed, 1021 insertions(+), 719 deletions(-) diff --git a/ipmitool/doc/ipmitool.1 b/ipmitool/doc/ipmitool.1 index 2445004..8b71925 100644 --- a/ipmitool/doc/ipmitool.1 +++ b/ipmitool/doc/ipmitool.1 @@ -2,42 +2,61 @@ .SH "NAME" ipmitool \- utility for controlling IPMI\-enabled devices .SH "SYNOPSIS" -ipmitool [\fB\-c\fR|\fB\-h\fR|\fB\-d \fIN\fP\fR|\fB\-v\fR|\fB\-V\fR] -\fB\-I\fR \fIopen\fP <\fIcommand\fP> -ipmitool [\fB\-c\fR|\fB\-h\fR|\fB\-v\fR|\fB\-V\fR] -\fB\-I\fR \fIlan\fP \fB\-H\fR <\fIhostname\fP> - [\fB\-p\fR <\fIport\fP>] - [\fB\-U\fR <\fIusername\fP>] - [\fB\-A\fR <\fIauthtype\fP>] - [\fB\-L\fR <\fIprivlvl\fP>] - [\fB\-a\fR|\fB\-E\fR|\fB\-P\fR|\fB\-f\fR <\fIpassword\fP>] - [\fB\-o\fR <\fIoemtype\fP>] - [\fB\-O\fR <\fIsel oem\fP>] - [\fB\-e\fR <\fIesc_char\fP>] - [\fB\-N\fR <\fIsec\fP>] - [\fB\-R\fR <\fIcount\fP>] - <\fIcommand\fP> +ipmitool [ ] [ ] + + := [ | ] +.br +Any recognized option is accepted. Conditional options may be ignored or it's usage postponed until shell or exec processes relevant command. +.br + + := [ -h | -V | -v | -I | -H
| + -d | -p | -c | -U | + -L | -l | -m | + -N | -R | | + | ] + + := [ | | + ] +.br +Bridging: +.br + := -t [ -b | + [ -T
| -B ] ] +.br + +Options used with -I lan: +.br + := [ -A ] +.br + +Options used with -I lanplus: +.br + := [ -C | ] +.br + +Option groups setting same value: +.br + := [ -k | -K | -y | -Y ] +.br + := [ -f | -a | -P | -E ] +.br + := [ -o | -g | -s ] +.br + +Options used with specific command : +.br + := [ -S ] +.br + := [ -O ] +.br + := [ -e ] + -ipmitool [\fB\-c\fR|\fB\-h\fR|\fB\-v\fR|\fB\-V\fR] -\fB\-I\fR \fIlanplus\fP \fB\-H\fR <\fIhostname\fP> - [\fB\-p\fR <\fIport\fP>] - [\fB\-U\fR <\fIusername\fP>] - [\fB\-L\fR <\fIprivlvl\fP>] - [\fB\-a\fR|\fB\-E\fR|\fB\-P\fR|\fB\-f\fR <\fIpassword\fP>] - [\fB\-o\fR <\fIoemtype\fP>] - [\fB\-O\fR <\fIsel oem\fP>] - [\fB\-C\fR <\fIciphersuite\fP>] - [\fB\-Y\fR|[\fB\-K\fR|\fB\-k\fR <\fIkg_key\fP>] - [\fB\-y\fR <\fIhex_kg_key\fP>] - [\fB\-e\fR <\fIesc_char\fP>] - [\fB\-N\fR <\fIsec\fP>] - [\fB\-R\fR <\fIcount\fP>] - <\fIcommand\fP> .SH "DESCRIPTION" This program lets you manage Intelligent Platform Management Interface (IPMI) functions of either the local system, via a kernel device driver, -or a remote system, using IPMI V1.5 and IPMI v2.0. These functions include +or a remote system, using IPMI v1.5 and IPMI v2.0. These functions include printing FRU information, LAN configuration, sensor readings, and remote chassis power control. @@ -64,46 +83,45 @@ Set destination channel for bridged request. \fB\-B\fR <\fIchannel\fP> Set transit channel for bridged request (dual bridge). .TP +\fB\-b\fR <\fIchannel\fP> +Set destination channel for bridged request. +.TP +\fB\-B\fR <\fIchannel\fP> +Set transit channel for bridged request. (dual bridge) +.TP \fB\-c\fR Present output in CSV (comma separated variable) format. This is not available with all commands. -.TP -\fB\-e\fR <\fIsol_escape_char\fP> -Use supplied character for SOL session escape character. The default -is to use \fI~\fP but this can conflict with ssh sessions. -.TP -\fB\-K\fR -Read Kg key from IPMI_KGKEY environment variable. -.TP -\fB\-k\fR <\fIkey\fP> -Use supplied Kg key for IPMIv2 authentication. The default is not to -use any Kg key. -.TP -\fB\-y\fR <\fIhex key\fP> -Use supplied Kg key for IPMIv2 authentication. The key is expected in -hexadecimal format and can be used to specify keys with non-printable -characters. E.g. '-k PASSWORD' and '-y 50415353574F5244' are -equivalent. -The default is not to use any Kg key. -.TP -\fB\-Y\fR -Prompt for the Kg key for IPMIv2 authentication. .TP \fB\-C\fR <\fIciphersuite\fP> The remote server authentication, integrity, and encryption algorithms -to use for IPMIv2 \fIlanplus\fP connections. See table 22\-19 in the -IPMIv2 specification. The default is 3 which specifies RAKP\-HMAC\-SHA1 -authentication, HMAC\-SHA1\-96 integrity, and AES\-CBC\-128 encryption algorightms. +to use for IPMIv2.0 \fIlanplus\fP connections. See table 22\-19 in the +IPMIv2.0 specification. The default is 3 which specifies RAKP\-HMAC\-SHA1 +authentication, HMAC\-SHA1\-96 integrity, and AES\-CBC\-128 encryption algorithms. +.TP +\fB\-d \fIN\fP\fR +Use device number N to specify the /dev/ipmiN (or +/dev/ipmi/N or /dev/ipmidev/N) device to use for in-band +BMC communication. Used to target a specific BMC on a +multi-node, multi-BMC system through the ipmi device +driver interface. Default is 0. +.TP +\fB\-e\fR <\fIsol_escape_char\fP> +Use supplied character for SOL session escape character. The default +is to use \fI~\fP but this can conflict with ssh sessions. .TP \fB\-E\fR The remote server password is specified by the environment -variable \fIIPMI_PASSWORD\fP. +variable \fIIPMI_PASSWORD\fP or \fIIPMITOOL_PASSWORD\fP. The \fIIPMITOOL_PASSWORD\fP takes precedence. .TP \fB\-f\fR <\fIpassword_file\fP> Specifies a file containing the remote server password. If this option is absent, or if password_file is empty, the password will default to NULL. .TP +\fB\-g\fR +Deprecated. Use: -o intelplus +.TP \fB\-h\fR Get basic usage help from the command line. .TP @@ -115,21 +133,35 @@ option is required for \fIlan\fP and \fIlanplus\fP interfaces. Selects IPMI interface to use. Supported interfaces that are compiled in are visible in the usage help output. .TP +\fB\-k\fR <\fIkey\fP> +Use supplied Kg key for IPMIv2.0 authentication. The default is not to +use any Kg key. +.TP +\fB\-K\fR +Read Kg key from IPMI_KGKEY environment variable. +.TP \fB\-l\fR <\fIlun\fP> Set destination lun for raw commands. .TP \fB\-L\fR <\fIprivlvl\fP> Force session privilege level. Can be CALLBACK, USER, OPERATOR, ADMINISTRATOR. Default is ADMINISTRATOR. +This value is ignored and always set to ADMINISTRATOR when +combined with \fI-t target address\fP. .TP \fB\-m\fR <\fIlocal_address\fP> Set the local IPMB address. The local address defaults to 0x20 or is auto discovered on PICMG platforms when -m is not specified. There should be no need to change the local address for normal operation. .TP +\fB\-M\fR <\fIaddress\fP> +Set transit local address for bridge request. (dual bridge) +.TP \fB\-N\fR <\fIsec\fP> Specify nr. of seconds between retransmissions of lan/lanplus messages. -Default are 2 seconds for lan and 1 second for lanplus interfaces. +Defaults are 2 seconds for lan and 1 second for lanplus interfaces. +Command \fIraw\fP uses fixed value of 15 seconds. +Command \fIsol\fP uses fixed value of 1 second. .TP \fB\-o\fR <\fIoemtype\fP> Select OEM type to support. This usually involves minor hacks @@ -140,7 +172,7 @@ current supported OEM types. \fB\-O\fR <\fIsel oem\fP> Open selected file and read OEM SEL event descriptions to be used during SEL listings. See examples in contrib dir for file format. -.TP +.TP \fB\-p\fR <\fIport\fP> Remote server UDP port to connect to. Default is 623. .TP @@ -152,6 +184,11 @@ option is not recommended. .TP \fB\-R\fR <\fIcount\fP> Set the number of retries for lan/lanplus interface (default=4). +Command \fIraw\fP uses fixed value of one try (no retries). +Command \fIhpm\fP uses fixed value of 10 retries. +.TP +\fB\-s\fR +Deprecated. Use: -o supermicro .TP \fB\-S\fR <\fIsdr_cache_file\fP> Use local file for remote SDR cache. Using a local SDR cache @@ -161,29 +198,43 @@ SDR cache from a remote system can be created with the \fIsdr dump\fP command. .TP \fB\-t\fR <\fItarget_address\fP> -Bridge IPMI requests to the remote target address. +Bridge IPMI requests to the remote target address. Default is 32. +The \fI-L privlvl\fP option is always ignored and value set to ADMINISTRATOR. .TP \fB\-T\fR <\fIaddress\fP> Set transit address for bridge request (dual bridge). .TP +\fB\-T\fR <\fItransmit_address\fP> +Set transit address for bridge request. (dual bridge) +.TP \fB\-U\fR <\fIusername\fP> Remote server username, default is NULL user. -.TP -\fB\-d \fIN\fP\fR -Use device number N to specify the /dev/ipmiN (or -/dev/ipmi/N or /dev/ipmidev/N) device to use for in-band -BMC communication. Used to target a specific BMC on a -multi-node, multi-BMC system through the ipmi device -driver interface. Default is 0. .TP \fB\-v\fR Increase verbose output level. This option may be specified multiple times to increase the level of debug output. If given three times you will get hexdumps of all incoming and -outgoing packets. +outgoing packets. Using it five times provides details +on request and expected reply procesing. The \fIhpm\fP commands +\fItargetcap\fP \fIcompprop\fP \fIabort\fP \fIupgstatus\fP +\fIrollback\fP \fIrollbackstatus\fP \fIselftestresult\fP increases +the verbosity level .TP \fB\-V\fR Display version information. +.TP +\fB\-y\fR <\fIhex key\fP> +Use supplied Kg key for IPMIv2.0 authentication. The key is expected in +hexadecimal format and can be used to specify keys with non-printable +characters. E.g. '-k PASSWORD' and '-y 50415353574F5244' are +equivalent. +The default is not to use any Kg key. +.TP +\fB\-Y\fR +Prompt for the Kg key for IPMIv2.0 authentication. +.TP +\fB\-z\fR <\fIsize\fP> +Change Size of Communication Channel. (OEM) .LP If no password method is specified then ipmitool will prompt the @@ -223,172 +274,42 @@ to get option usage help. ipmitool help .br Commands: - raw Send a RAW IPMI request and print response - i2c Send an I2C Master Write-Read command and print response - spd Print SPD info from remote I2C device - lan Configure LAN Channels - chassis Get chassis status and set power state - power Shortcut to chassis power commands - event Send events to MC - mc Management Controller status and global enables - sdr Print Sensor Data Repository entries and readings - sensor Print detailed sensor information - fru Print built\-in FRU and scan for FRU locators - sel Print System Event Log (SEL) - pef Configure Platform Event Filtering (PEF) - sol Configure and connect IPMIv2.0 Serial\-over\-LAN - tsol Configure and connect Tyan IPMIv1.5 Serial\-over\-LAN - isol Configure and connect Intel IPMIv1.5 Serial\-over\-LAN - user Configure Management Controller users + bmc Deprecated. Use mc channel Configure Management Controller channels + chassis Get chassis status and set power state dcmi Data Center Management Interface - session Print session information - sunoem Manage Sun OEM Extensions - kontronoem Manage Kontron OEM Extensions - picmg Run a PICMG/ATA extended command - firewall Configure Firmware Firewall - shell Launch interactive IPMI shell - exec Run list of commands from file - set Set runtime variable for shell and exec delloem Manage Dell OEM Extensions. echo Used to echo lines to stdout in scripts ekanalyzer run FRU-Ekeying analyzer using FRU files - ime Upgrade/Query Intel ME firmware - hpm Update HPM components using PICMG HPM.1 file + event Send events to MC + exec Run list of commands from file + firewall Configure Firmware Firewall + fru Print built\-in FRU and scan for FRU locators fwum Update IPMC using Kontron OEM Firmware Update Manager + gendev Read/Write Device associated with Generic Device locators sdr + hpm Update HPM components using PICMG HPM.1 file + i2c Send an I2C Master Write-Read command and print response + ime Upgrade/Query Intel ME firmware + isol Configure and connect Intel IPMIv1.5 Serial\-over\-LAN + kontronoem Manage Kontron OEM Extensions + lan Configure LAN Channels + mc Management Controller status and global enables + pef Configure Platform Event Filtering (PEF) + picmg Run a PICMG/ATA extended command + power Shortcut to chassis power commands + raw Send a RAW IPMI request and print response + sdr Print Sensor Data Repository entries and readings + sel Print System Event Log (SEL) + sensor Print detailed sensor information + session Print session information + set Set runtime variable for shell and exec + shell Launch interactive IPMI shell + sol Configure and connect IPMIv2.0 Serial\-over\-LAN + spd Print SPD info from remote I2C device + sunoem Manage Sun OEM Extensions + tsol Configure and connect Tyan IPMIv1.5 Serial\-over\-LAN + user Configure Management Controller users - -ipmitool chassis help -.br -Chassis Commands: status, power, identify, policy, restart_cause, poh, bootdev, bootparam, selftest - -ipmitool chassis power help -.br -chassis power Commands: status, on, off, cycle, reset, diag, soft -.TP -\fIbmc|mc\fP -.RS -.TP -\fIreset\fP <\fBwarm\fR|\fBcold\fR> -.br - -Instructs the BMC to perform a warm or cold reset. -.TP -\fIguid\fP - -Display the Management Controller Globally Unique IDentifier. -.TP -\fIinfo\fP -.br - -Displays information about the BMC hardware, including device -revision, firmware revision, IPMI version supported, manufacturer ID, -and information on additional device support. -.TP -\fIwatchdog\fP -.br - -These commands allow a user to view and change the current -state of the watchdog timer. -.RS -.TP -\fIget\fP -.br - -Show current Watchdog Timer settings and countdown state. -.TP -\fIreset\fP -.br - -Reset the Watchdog Timer to its most recent state and restart the -countdown timer. -.TP -\fIoff\fP -.br - -Turn off a currently running Watchdog countdown timer. -.RE -.TP -\fIselftest\fP -.br - -Check on the basic health of the BMC by executing the Get Self Test -results command and report the results. -.TP -\fIgetenables\fP -.br - -Displays a list of the currently enabled options for the BMC. -.br -.TP -\fIsetenables\fP <\fBoption\fR>=[\fIon\fP|\fIoff\fP] -.br - -Enables or disables the given \fIoption\fR. This command is -only supported over the system interface according to the IPMI -specification. Currently supported values for \fIoption\fR include: -.RS -.TP -\fIrecv_msg_intr\fP -.br - -Receive Message Queue Interrupt -.TP -\fIevent_msg_intr\fP -.br - -Event Message Buffer Full Interrupt -.TP -\fIevent_msg\fP -.br - -Event Message Buffer -.TP -\fIsystem_event_log\fP -.br - -System Event Logging -.TP -\fIoem0\fP -.br - -OEM\-Defined option #0 -.TP -\fIoem1\fP -.br - -OEM\-Defined option #1 -.TP -\fIoem2\fP -.br - -OEM\-Defined option #2 - -.RE -.TP -\fIgetsysinfo\fP <\fBargument\fP> -Retrieves system info from bmc for given argument. -.br -See \fIsetsysinfo\fP for argument definitions -.TP -\fIsetsysinfo\fP <\fBargument\fP> <\fBstring\fP> -Stores system info string to bmc for given argument -.RS -.TP -Possible arguments are: -.RS -.TP -\fIprimary_os_name\fP Primary Operating System Name -.TP -\fIos_name\fP Operating System Name -.TP -\fIsystem_name\fP System Name of Server -.TP -\fIdelloem_os_version\fP Running versin of operating system -.TP -\fIdelloem_URL\fP URL of BMC Webserver -.RE -.RE .TP \fIchannel\fP .RS @@ -410,6 +331,8 @@ Possible privilege levels are: \fI4\fP Administrator level .br \fI5\fP OEM Proprietary level +.br +\fI15\fP No access .RE .TP \fIinfo\fP [\fBchannel number\fR] @@ -434,7 +357,7 @@ Channel 0xf info: .RE .TP \fIgetaccess\fP <\fBchannel number\fR> [<\fBuserid\fR>] -.br +.RS Configure the given userid as the default on the given channel number. When the given channel is subsequently used, the user is identified @@ -452,243 +375,193 @@ Configure user access information on the given channel for the given userid. Displays the list of cipher suites supported for the given application (ipmi or sol) on the given channel. .RE +.RE .TP \fIchassis\fP .RS .TP \fIstatus\fP -.br -Displays information regarding the high\-level -status of the system chassis and main power -subsystem. -.TP -\fIpoh\fP -.br - -This command will return the Power\-On Hours counter. -.TP -\fIidentify\fP <\fBinterval\fR> - -Control the front panel identify light. Default interval -is 15 seconds. Use 0 to turn off. Use "force" to turn on -indefinitely. -.TP -\fIrestart_cause\fP -.br - -Query the chassis for the cause of the last system restart. -.TP -\fIselftest\fP -.br - -Check on the basic health of the BMC by executing the Get Self Test -results command and report the results. -.TP -\fIpolicy\fP -.br - -Set the chassis power policy in the event power failure. +Status information related to power, buttons, cooling, drives and faults. .RS -.TP -\fIlist\fP -.br - -Return supported policies. -.TP -\fIalways\-on\fP -.br - -Turn on when power is restored. -.TP -\fIprevious\fP -.br - -Returned to previous state when power is restored. -.TP -\fIalways\-off\fP -.br - -Stay off after power is restored. .RE .TP \fIpower\fP -.br - -Performs a chassis control command to view and -change the power state. .RS .TP \fIstatus\fP -.br - -Show current chassis power status. -.TP +.RS +.RE +.TP \fIon\fP -.br - -Power up chassis. -.TP +.RS +.RE +.TP \fIoff\fP -.br - -Power down chassis into soft off (S4/S5 state). -\fBWARNING\fR: This command does not initiate a clean -shutdown of the operating system prior to powering down the system. -.TP +.RS +.RE +.TP \fIcycle\fP -.br - -Provides a power off interval of at least 1 second. No action -should occur if chassis power is in S4/S5 state, but it is -recommended to check power state first and only issue a power -cycle command if the system power is on or in lower sleep -state than S4/S5. -.TP +.RS +.RE +.TP \fIreset\fP -.br - -This command will perform a hard reset. -.TP +.RS +.RE +.TP \fIdiag\fP -.br - -Pulse a diagnostic interrupt (NMI) directly to the processor(s). -.TP +.RS +.RE +.TP \fIsoft\fP -.br - -Initiate a soft\-shutdown of OS via ACPI. This can be done in a -number of ways, commonly by simulating an overtemperture or by -simulating a power button press. It is necessary for there to -be Operating System support for ACPI and some sort of daemon -watching for events for this soft power to work. +.RS +.RE .RE .TP -\fIbootdev\fP <\fBdevice\fR> [<\fIclear\-cmos\fP=\fByes\fR|\fBno\fR>] [<\fIoptions\fP=\fBhelp,...\fR>] -.br +\fIidentify\fP [|force] -Request the system to boot from an alternate boot device on next reboot. -The \fIclear\-cmos\fP option, if supplied, will instruct the BIOS to -clear its CMOS on the next reboot. Various options may be used to modify -the boot device settings. Run \fI"bootdev none options=help"\fP for a list of -available boot device modifiers/options. +Identify interval. +.br +Default is 15 seconds. +.br +0 - Off +.br +force - To turn on indefinitely +.RS +.RE +.TP +\fIpolicy\fP +What to do when power is restored. .RS .TP -Currently supported values for are: +\fIlist\fP + +Show available options. +.RS +.RE +.TP +\fIalways-on\fP +.RS +.RE +.TP +\fIprevious\fP +.RS +.RE +.TP +\fIalways-off\fP +.RS +.RE +.RE + +.TP +\fIrestart_cause\fP + +Last restart cause. +.RS +.RE +.TP +\fIpoh\fP + +Get power on hours. +.RS +.RE +.TP +\fIbootdev\fP +.RS .TP \fInone\fP -.br -Do not change boot device +Do not change boot device order. +.RS +.RE .TP \fIpxe\fP -.br -Force PXE boot +Force PXE boot. +.RS +.RE .TP \fIdisk\fP -.br -Force boot from BIOS default boot device +Force boot from default Hard-drive. +.RS +.RE .TP \fIsafe\fP -.br -Force boot from BIOS default boot device, request Safe Mode +Force boot from default Hard-drive, request Safe Mode. +.RS +.RE .TP \fIdiag\fP -.br -Force boot from diagnostic partition +Force boot from Diagnostic Partition. +.RS +.RE .TP \fIcdrom\fP -.br -Force boot from CD/DVD +Force boot from CD/DVD. +.RS +.RE .TP \fIbios\fP -.br -Force boot into BIOS setup +Force boot into BIOS Setup. +.RS +.RE .TP \fIfloppy\fP -.br -Force boot from Floppy/primary removable media +Force boot from Floppy/primary removable media. +.RS +.RE .RE .TP \fIbootparam\fP -.br - -Get or set various system boot option parameters. .RS .TP -\fIget\fP <\fBparam #\fR> -.br - -Get boot parameter. Currently supported values for <\fBparam #\fR> are: - -\fI0\fP - Set In Progress - -\fI1\fP - Service Partition Selector - -\fI2\fP - Service Partition Scan - -\fI3\fP - BMC Boot Flag Valid Bit Clearing - -\fI4\fP - Boot Info Acknowledge - -\fI5\fP - Boot Flags - -\fI6\fP - Boot Initiator Info - -\fI7\fP - Boot Initiator Mailbox -.br - -.TP -\fIset\fP <\fBoption\fR> [\fBvalue ...\fR] -.br - -Set boot parameter. - -.RS -.TP -Currently supported values for \fB