package: openipmi-ui

title: ipmi_cmdlang(7)

text:
# ipmi_cmdlang(7)

## NAME
ipmi_cmdlang - A command language interface to the IPMI library

## DESCRIPTION
ipmi_cmdlang is a command language designed to supply the full power of OpenIPMI on a command line. It has a large number of commands and well-formed responses to each command. Note that this assumes some knowledge of OpenIPMI and how it works; you can get that from the IPMI document that comes with OpenIPMI.

ipmish starts up with no connections or anything of that nature. You must enter commands to make connections to domains. Then you can enter commands to manipulate those domains or objects inside those domains.

Note that you may use quotes, either '' or to contain parameters with spaces.

## COMMENTS
Lines with a # character in the first column are ignored.

## OBJECTS
In the command language, you will deal with various objects like sensors, controls, domains, and entities. Each of these has a name. The name of the domain is assigned by the user in the domain new command, all the other names are based on the domain name of the domain they belong to and various attributes about the object. These names are all well-formed. They are

<domain> - A name of a domain. Each registered domain in a system has a name assigned by the user.

<entity> - Entity names are in the form:

[<domain>[(<entity spec>)]]

Notice that the <entity spec> is optional. If it is not listed, then the operation is done on all entities in the domain. The whole thing is optional, too, if nothing is given then the operation is done on every entity in every domain. The <entity spec> is either

<entity id>.<entity instance>

for system-relative entities, or: r<channel>.<IPMB>.<entity id>.<entity instance-0x60>

for device-relative entities. In IPMI, device-relative entity instances always start at 0x60; the specification suggests that you subtract off the 0x60 from the entity instance when displaying these; the command language follows this suggestion. <sensor> - These come in the form

[<entity>[.name]]

As with entities, only listing a domain will cause the operation to be done on every sensor in the domain, just listing an entity will cause it to be done to every sensor in that entity. An empty sensor entry will cause an operation to be done on every sensor in every domain. <control> - These come in the form

[<entity>[.name]]

These work exactly like sensors. <mc> - A management controller. These come in the form

[<domain>[(<channel>.<IPMB>)]]

As usual, the parts left empty will cause defaulting to all things in the previously specified parts. <connection> - A connection number, in the form

[<domain>[.<integer>]]

The number is the connection number of the domain. <pet> - A platform event trap id, in the form

[<domain>[.<integer>]]

The number is arbitrarily assigned by the system. <lanparm> - A LAN parameter id, in the form

[<domain>[.<integer>]]

The number is arbitrarily assigned by the system. <pef> - A PEF id, in the form

[<domain>[.<integer>]]

The number is arbitrarily assigned by the system. <fru> - A FRU id, in the form

[<domain>[.<integer>]]

The number is arbitrarily assigned by the system. In all cases, the object names have parts that are optional, and the entire object name is optional. If a part is left empty, then all objects that are part of the specified parts are operated on. For instance, if the system has a sensor named d1(7.1).temp then specifying d1 would operation on all sensors in the domain named d1. Specifying d1(7.1) Would operation on all sensors in that entity. Specifying an empty name, either with or by just entering nothing if the object is the last thing in the command's parameters.

Note this optionality gives a lot of power, but can be very dangerous. Entering domain close will close every domain, for instance.

In commands, every object operated on will generate a response for that object. If no object is operated on, the command will produce an error.

## OTHER PARAMETERS
The commands and displays use a variety of other parameters for specifying various IPMI things.

<guid> - a 16-byte globally unique ID, all globbed together in one big hexadecimal thing.

<threshold> is a threshold for a sensor; the value it must go over/under to generate an event. It is always displayed as one of lower non-critical lower critical lower non-recoverable upper non-critical upper critical upper non-recoverable. It may be entered as one of the above, or as ln, lc, lr, un, uc, ur as a short form.

<threshold enable> is the enable for a threshold. It is like <threshold> above, but also has a going-high or going-low and an assertion or deassertion appended to the end of the name. The short form will have a l or h for going-low and going high and then a a or d appended for assertion and deassertion So for instance, urld is upper non-recoverable going-low deassertion.

<discrete enable> is the enable or disable for a discrete sensor and is specified with the sensor offset. The long form is <integer> assertion or <integer> deassertion and the short form is <integer>[ad] where the number is the offset and [ad] means assertion or deassertion.

<hot-swap state> is one of not_present, inactive activation_requested activation_in_progress active deactivation_requested deactivation_in_progress or out_of_con.

<color> is one of black, white, red, green blue yellow or orange.

<bool> is one of true, on, t, or 1 for true and one of false, off, f, or 0 for false. Output is always true or false.

## COMMANDS
The command language is hierarchical, meaning that commands may have subcommands, and subcommands may have subsubcommands, etc. So, for instance, the command to create a domain is domain new. The command to list all sensors in a domain named domain1 is sensor list domain1.

Each command has a reponse for each object operated on, which is listed after the command description. In those responses, anything that begins with a % is optional. Entries of the form **name** refer to object info descriptions that are listed in the object info section. If an entry has two '.' indented one space below it, then that entry may occur zero or more times.

Each section below defines the unique subcommands of a main command.

Help for any command is available with:

help command [subcommand [...]] - Help for any command.

Some commands are common to almost all subcommands. These are:

list <containing object> - List all objects of the specified type that are contained in the specified object. For instance, control list <entity> will list all controls in the given entity.

Response:

```
<containing object type>

  Name: <name>

   .

   .
```

info <object> - List static information about the given object.

Response:

```
<object type>

  Name: <name>

  **object info**
```

### domain
These commands deal with domain objects.

new <domain> <options> <parms> [<parms>] - Open a connection to a new domain. <parms> are either:

lan <IP> <port> [<IP> <port>] <enc> <auth> <name> <password>

for a RMCP LAN connection or smi <smi num>

for a system interface connection. Note that <parms> is listed twice (second one is optional); if the system support it you can make two connections to two independent management controllers in the system. Note that this is not for multiple IP addresses to the same BMC. For that, notice that the LAN connection has an options extra IP and port for the second IP address. OpenIPMI supports these IP addresses and connection, detecting failures, switching between addresses, and other fault-tolerant things. It does this transparently to the user. Mutiple connections may require special OEM support, read the documentation about your specific system if you need this. The <IP> is the IP address or host name of the LAN-capable BMC to connect with. The <port> is generally 623. <enc> is the authentication type, either md5, md2, straight, or none. <auth> is the authentication level, either admin, operator or user. <name> and <password> are the user name and password of the IPMI user to use for the connection. The <smi num> is the driver number, generally 0. Options enable and disable various automitic processing and are:

-[no]all - all automatic handling. This will override the other processing options and turn them all on. This is true by default.

-[no]sdrs - sdr fetching. This turns on fetching SDRs when they are found. This is false by default.

-[no]frus - FRU fetching This turns on fetching FRU information when it is found. This is false by default.

-[no]sel - SEL fetching. This turns on fetching SELs when they are found. This is false by default.

-[no]ipmbscan - IPMB bus scanning. This turns on scanning IPMB busses when they are found. This is false by default.

-[no]oeminit - enable or disable special OEM processing (like ATCA).

-[no]seteventrcvr - setting event receivers. Note that setting event receivers and waiting til up is not affected by the -all option. If this is true (the default) then OpenIPMI will attempt to set the event receiver for an MC it finds that does not have it set to a valid destination.

-wait_til_up - wait until the domain is up before returning Note that if you specify this and the domain never comes up, you will never get a prompt. This is not affected by the -all option. By default -all and -seteventrcvr are true, which turns everything on.

Response:

```
Domain Created: <domain>
```

open <domain> <options> <parms> [<parms>] - Open a connection to a new domain. <parms> are either:

lan [-U <username>] [-P <password>] [-A <authtype>]

[-L <privilege>] [-s] [-p[2] <port number>]

[-Ra <auth alg>] [-Ri <integ alg>] [-Rc <conf algo>]

[-Rl] [-Rk <bmc key>] [-H <hackname>]

[-M <max oustanding msgs>] <IP> [<IP>]

for a RMCP/RMCP+ LAN connection or smi <smi num>

for a system interface connection. Note that <parms> is listed twice (second one is optional); if the system support it you can make two connections to two independent management controllers in the system. Note that this is not for multiple IP addresses to the same BMC. For that, use the -s option and the second IP (and -p2) for the second IP address. OpenIPMI supports these IP addresses and connections, detecting failures, switching between addresses, and other fault-tolerant things. It does this transparently to the user. Multiple connections may require special OEM support, read the documentation about your specific system if you need this. The <IP> is the IP address or host name of the LAN-capable BMC to connect with. The <port> defaults 623. <authtype> is the authentication type, either rmcp+, md5, md2, straight, or none. It defaults to the best authentication supported by the server. <auth> is the authentication level, either admin, operator or user. It defaults to admin. <username> and <password> are the user name and password of the IPMI user to use for the connection. For RMCP+ connections, the authentication algorithms supported (-Ra) are: bmcpick, rakp_none, rakp_hmac_sha1, and rakp_hmac_md5. The integrity algorithms (-Ri) supported are: bmcpick, none, hmac_sha1, hmac_md5, and md5. The confidentiality algorithms (-Rc) are: bmcpick, aes_cbc_128, xrc4_128, and xrc_40. The defaults are rackp_hmac_sha1, hmac_sha1, and aes_cb_128. -Rl turns on lookup up names by the name and the privilege level (allowing the same name with different privileges and different passwords), the default is straight name lookup. -Rk sets the BMC key, needed if the system does two-key lookups.

For SMI types, the <smi num> is the driver number, generally 0.

The <hackname> enables certain hacks for broken platforms. This may be listed multiple times to enable multiple hacks. The currently available hacks are:

intelplus - For Intel platforms that have broken RMCP+.

rakp3_wrong_rolem - For systems that truncate role(m) in the RAKP3 msg.

rmcpp_integ_sik - For systems that use SIK instead of K(1) for integrity.

The -M option sets the maximum outstanding messages. The default is 2, ranges 1-63.

Options enable and disable various automitic processing and are:

-[no]all - all automatic handling. This will override the other processing options and turn them all on. This is true by default.

-[no]sdrs - sdr fetching. This turns on fetching SDRs when they are found. This is false by default.

-[no]frus - FRU fetching This turns on fetching FRU information when it is found. This is false by default.

-[no]sel - SEL fetching. This turns on fetching SELs when they are found. This is false by default.

-[no]ipmbscan - IPMB bus scanning. This turns on scanning IPMB busses when they are found. This is false by default.

-[no]oeminit - enable or disable special OEM processing (like ATCA).

-[no]seteventrcvr - setting event receivers. Note that setting event receivers is not affected by the -all option. If this is true (the default) then OpenIPMI will attempt to set the event receiver for an MC it finds that does not have it set to a valid destination. -[no]setseltime - set SEL time. Note that setting the SEL time is not affected by the -all option. If this is true (the default) then OpenIPMI will attempt to set the time in the SELs it finds. It will set it to the current system time.

-wait_til_up - wait until the domain is up before returning Note that if you specify this and the domain never comes up, you will never get a prompt. This is not affected by the -all option. By default -all and -seteventrcvr are true, which turns everything on.

Response:

```
Domain Created: <domain>
```

fru <domain> <is_logical> <device_address> <device_id> <lun> <private_bus> <channel> - dump a fru given all it's insundry information.

Response:

```
Domain

  Name: <domain>

  FRU

    **FRU INFO**
```

msg <domain> <channel> <ipmb> <LUN> <NetFN> <Cmd> [data...] - Send a command to the given IPMB address on the given channel and display the response. Note that this does not require the existance of an MC in OpenIPMI.

Response:

```
  Domain: <domain>

  channel: <chan>

  ipmb: <ipmb>

  LUN: <lun>

  NetFN: <netfn>

  command: <cmd>

  Data: <data bytes>
```

scan <domain> <ipmb addr> [ipmb addr] - scan an IPMB to add or remove it. If a range is given, then scan all IPMBs in the range.

Response:

```
Scan done: <domain>
```

rescan_sels <domain> - Rescan all the SELs in the domain.

Response:

```
SEL Rescan done: <domain>
```

presence <domain> - Audit the presence of all enities in the domain. Note that this just starts the process; it will run in the background.

Response is:

```
Presence check started: <domain>
```

close <domain> - close the given domain.

Response:

```
Domain closed: <domain>
```

sel_rescan_time <domain> <time in seconds> - Set the time between SEL rescans for all. It affects all current SELs and SELs that are discovered in the future. Zero disables scans.

Response:

```
Domain SEL rescan time set: <domain>
```

ipmb_rescan_time <domain> <time in seconds> - Set the time between IPMB rescans for this domain. zero disables scans.

Response:

```
Domain IPMB rescan time set: <domain>
```

### fru
These commands deal with FRU objects. Note that FRU objects are allocated by the domain fru command, and are not allocated here.

list - List all the frus in the system

Response:

```
Domain

  Name: <domain>

  FRUs

    Name: <fru>

   .

   .

 .

 .
```

info <fru> - Dump information about a FRU

Response:

```
**FRU INFO**
```

areainfo <fru> - Dump the info about the FRU's areas

Response:

```
FRU

  Name: <fru>

  FRU Length: <integer>

  Area

    Name: <area name>

    Number: <integer>

    Offset: <integer>

    Length: <integer>

    Used Length: <Integer>

   .

   .
```

write <fru> - Write the local FRU data out into the FRU

Response:

```
FRU written: <fru>
```

close <fru> - Delete the FRU

Response:

```
FRU deleted: <fru>
```

setval <fru> <name> [num] value - Set the value of a FRU element. The name is the record name, or multi-record. The number is required for fields that need it (custom and multi-record). The value is an a single value for integers. For strings it is a string type (either binary, ascii, or unicode) and the info. Binary and unicode data is specified as numbers. ascii data is specified in a string. Note that setting a ascii value with no string will clear the value. Zero length strings and data is valid.

Response:

```
FRU value set: <fru>
```

area_offset <fru> <area name> <offset> - Set the offset of the given area to the given value. Area names are internal_data, chassis_info, board_info, product_info, and multi_record.

Response:

```
FRU area offset set: <fru>
```

area_length <fru> <area name> <length> - Set the length of the given area to the given value. Area names are internal_data, chassis_info board_info, product_info, and multi_record

Response:

```
FRU area length set: <fru>
```

area_add <fru> <area name> <offset> <length> - Add the given area to the FRU.

Response:

```
FRU area added: <fru>
```

area_delete <fru> <area name> - Delete the given area from the FRU

Response:

```
FRU area deleted: <fru>
```

### entity
These commands deal with entity objects.

list <entity> - List all the entities that meed the criteria

Response:

```
Domain

  Name: <domain>

  Entities

    Name: <entity>

     .

     .

 .

 .
```

info <entity> - Dump information about an entity.

Reponse:

```
Entity

  Name: <entity>

  **ENTITY INFO**

 .

 .
```

fru <entity> - Dump the FRU information about the given entity.

Reponse:

```
Entity

  Name: <entity>

  FRU

    **FRU INFO**
```

### entity hs
These commands deal with hot-swap of entities. Note that there is no info or list command for this subcommand.

get_act_time <entity> - Get the hot-swap auto-activate time.

Response:

```
Entity

  Name: <entity>

    Auto-Activation Time: <integer>
```

set_act_time <entity> - Set the hot-swap auto-activate time.

Reponse:

```
Set act time: <entity>
```

get_deact_time <entity> - Get the hot-swap auto-deactivate time Response:

```
Entity

  Name: <entity>
	Auto-Deactivation Time: <integer>
```

set_deact_time <entity> - Set the hot-swap auto-deactivate time

Response:

```
Set deact time: <entity>
```

activation_request <entity> - Act like a user requested an activation of the entity. This is generally equivalent to closing the handle latch or something like that.

Response:

```
Activation requested: <entity>
```

activate <entity> - activate the given entity

Response:

```
Activated: <entity>
```

deactivate <entity> - deactivate the given entity

Response:

```
Deactivated: <entity>
```

state <entity> - Return the current hot-swap state of the given entity.

Response:

```
Entity

  Name: <entity>

    State: <hot-swap state>
```

check <entity> - Audit the entity's hot-swap state

Response:

```
Check started: <entity>
```

### sensor
get <sensor> - Get the sensor's current reading.

Response:

```
Sensor

  Name: <sensor>

  Event Messages Enabled: <bool>

  Sensor Scanning Enabled: <bool>

  Initial Update In Progress: <bool>
```

For threshold sensors, the following will be output:

```
%Value: <double>
%Raw Value: <integer>
Threshold

  Name: <threshold>

  Out Of Range: <bool>
```

For discrete sensors, the following will be output:

```
Event

  Offset: <integer>

  %Name: <string name of event offset>

  Set: <bool>
```

The name field may be custom and is not explicitly specified. rearm <sensor> global | <threshold enable> [<threshold enable> ..] | <discrete enable> [<discrete enable> ..] - Rearm the sensor. If global is specified, then rearm all events in the sensor. Otherwise, if it is a threshold sensor, then put in a list of threshold enables. If it is a discrete sensor, then put in a list of discrete enables.

Response:

```
Rearm done: <sensor>
```

get_thresholds <sensor> - Get the sensor's thresholds

Response:

```
Sensor

  Name: <sensor>

  Threshold

    Name: <threshold>

    Value: <double>
```

set_thresholds <sensor> <threshold> <value> ... - Set the sensor's thresholds to the given values. If a threshold is not specified, it will not be modified. Thresholds are un, uc, ur, lr, lc, ln. The u stands for upper, l for lower, n for non-critical, c for critical, and r for non-recoverable. The value is floating point.

Response:

```
Thresholds set: <sensor>
```

get_hysteresis <sensor> - Get the sensor's hysteresis values

Response:

```
Sensor

  Name: <sensor>

  Positivie Hysteresis: <integer>

  Negative Hysteresis: <integer>
```

set_hysteresis <sensor> <pos hyst> <neg hyst> - Set the sensor's hysteresis to the given values. These are raw integer value; hystersis is specified as a raw value and it cannot be converted to floating point because the function may be non-linear.

Response:

```
Hysteresis set: <sensor>
```

get_event_enables <sensor> - Get the sensor's event enable values

Response:

```
Sensor

  Name: <sensor>

  Event Messages Enabled: <bool>

  Sensor Scanning Enabled: <bool>

  Busy: <bool>
```

Threshold sensors report:

```
Threshold

  Name: <threshold>

  Enabled: <bool>

   .

   .
```

only supported thresholds are listed. Discrete sensors report:

```
Event

  Offset: <integer>

  Name: <event offset name for sensor>

  %Assertion Enabled: <bool>

  %Deassertion Enabled: <bool>
```

only supported offsets are listed. The assertion and deassertion enables are listed only if the offset support them. set_event_enables <sensor> msg|nomsg scan|noscan [<enable> [<enable> ...]] - Set the sensor's event enable values. This turns sensor messages and scanning on and off and will enable all the listed enables and disable all over ones. The enables are either a <threshold enable> or a <discrete enable>.

Response:

```
Event enables set: <sensor>
```

enable_events <sensor> msg|nomsg scan|noscan [<enable> [<enable> ...]] - Enable event enable values. This turns sensor messages and scanning on and off and will enable all the listed enables. All other enables will be left alone. The enables are either a <threshold enable> or a <discrete enable>.

Response:

```
Event enables set: <sensor>
```

disable_events <sensor> msg|nomsg scan|noscan [<enable> [<enable> ...]] - Disable event enable values. This turns sensor messages and scanning on and off and will disable all the listed enable. All other enables will be left alone. The enables are either a <threshold enable> or a <discrete enable>.

Response:

```
Event enables set: <sensor>
```

### control
Commands dealing with controls.

set <control> <value> [<value> ..] - Set the value of a control. The settings depend on control type, most take one or more integer values depending on the number of physical things the control contains. An identifier type takes one or more unsigned characters. A light set with settings take the form

lc|nolc <color> <on time> <off time>

lc and nolc turn on or of local control, the over values should be obvious. Note all lights support local control, you need to see if it supports the value. Response:

```
Set done: <control>
```

get <control> - Get the value of a control. The reponse depends on the control type.

Response:

```
Control

  Name: <control>
```

Response for setting lights is:

```
Light

  Num: 0

  Local Control: <bool>

  %Color: <color>

  %On Time: <integer>

  %Off Time: <integer>
```

Note that multiple lights may be present if the control supports multiple lights. The options values (marked with % ) will not be present if local control is set to true. Local control means that the LED takes whatever default function it does on the device (like disk activity, ethernet activity, hot-swap LED, etc.). Response for id control:

```
Data: <byte1> <byte2> ...
```

Response for other controls:

```
Value

  Num: <integer>

  Value: <integer>
```

There will be one Value for each value the control supports.

### mc
Commands dealing with MC objects.

reset <warm | cold> <mc> - Do a warm or cold reset on the given MC

Response:

```
Reset done: <mc>
```

msg <mc> <LUN> <NetFN> <Cmd> [data...] - Send the given command to the management controller and display the response.

Response:

```
  MC: <mc>

  LUN: <lun>

  NetFN: <netfn>

  command: <cmd>

  Data: <data bytes>
```

set_events_enable <mc> <enable | disable> - enables or disables events on the MC.

Response:

```
Events enable done: <mc>
```

get_events_enable <mc> - Prints out if the events are enabled for the given MC.

Response:

```
Events Enable: <bool>
```

sdrs <mc> <main | sensor> - list the SDRs for the mc. Either gets the main SDR repository or the sensor SDR repository.

Response:

```
MC

  Name: <mc>

  SDR

    Record ID: <integer>

    Type: <integer>

    Version: <integer>.<integer>

    Data: <data bytes>
```

One SDR will be present for each SDR in the repository. get_sel_time <mc> - Get the time in the SEL for the given MC.

Response:

```
MC

  Name: <mc>

  SEL Time: <integer>
```

set_sel_time <mc> <time> - Set the time in the SEL for the given MC.

Response:

```
MC SEL time set

  Name: <mc>
```

rescan_sel <mc> - Rescan the SEL in the MC.

Response:

```
SEL Rescan done: <mc>
```

sel_rescan_time <mc> <time in seconds> - Set the time between SEL rescans for the SEL on this MC. Zero disables scans.

Response:

```
MC SEL rescan time set: <domain>
```

sel_info <mc> - Dump information about the MC's SEL.

Response:

```
MC

  Name: <mc>

  SEL Version: <integer>.<integer>

  SEL Count: <integer>

  SEL Slots Used: <integer>

  SEL Free Bytes: <integer>

  SEL Last Addition Timestamp: <integer>

  SEL overflow: <bool>

  SEL Supports Delete: <bool>

  SEL Supports Partial Add: <bool>

  SEL Supports Reserve: <bool>

  SEL Supports Get SEL Allocation: <bool>
```

chan info <mc> <channel> - Dump information about the MC's channel.

Response:

```
Channel Info

  MC: <mc>

  Number: <integer>

  Medium: <integer>

  Protocol Type: <integer>

  Session Support: session-less|single-session|multi-session|session-based

  Vendor ID: <data bytes>

  Aux Info: <data bytes>
```

chan get_access <mc> <channel> non-volatile|present|both - Dump information about the MC's channel access. There are two different places where this is stored, the present in-use values (volatile) and the non-volatile storage that is loaded at startup. Note if you specify channel 0xe, the response channel will be different; it will be the current channel.

Response:

```
Channel Access

  MC: <mc>

  Channel: <integer>

  Type: non-volatile|present

  Alerting Enabled: <bool>

  Per-Message Auth: <bool>

  User Auth: <bool>

  Access Mode: disable|pre-boot|always|shared

  Privilege Limit: callback|user|operator|admin|oem
```

chan set_access <mc> <channel> non-volatile|present|both <parm> <value> ... - Set information about the MC's channel access. There are two different places where this is stored, the present in-use values (volatile) and the non-volatile storage that is loaded at startup. Note if you specify channel 0xe, the modified channel will be the current channel. Parms are:

```
alert true|false
msg_auth true|false
user_auth true|false
access_mode disabled|pre-boot|always|shared
privilege_limit callback|user|operator|admin|oem
```

Response:

```
Channel Access Set

  MC: <mc>

  Channel: <integer>
```

chan user list <mc> <channel> [<user num>] - List users associated with the channel. Each user number has an associated name and password that is global in the MC (not associated with a channel). There is also channel-specific information for each user. This command lists the global user information and the channel-specific information for the channel specified. If no user number is listed, then all users for the channel are listed. Otherwise only the given user is listed.

Response:

```
Channel Access Set

  MC: <mc>

  Channel: <integer>

  Max User: <integer>

  Enabled Users: <integer>

  Fixed Users: <integer>

  User

    Number: <integer>

    *String Name: <string>

    *Binary Name: <data bytes>

   Link Auth Enabled: <bool>

   Msg Auth Enabled: <bool>

   Access CB Only: <bool>

   Privilege Limit: <integer>

   Session Limit: <integer>

  .

  .
```

All the users are listed. One of string name or binary name is present, if the name is not a printable string, then the binary data is dumped. chan user set <mc> <channel> <user num> <parm> <value> ... - Set information about the user number. Only the specified values are modified. The name and password are global values, all other are channel-specific. The parms are: are:

```
link_enabled true|false
msg_enabled true|false
cb_only true|false
privilege_limit callback|user|operator|admin|oem|no_access
session_limit <integer>
name <user name string>
password <password string, <= 16 characters>
password2 <password string, <= 20 characters>
enable
disable
```

The password is the 16-byte IPMI 1.5 passwords., the password2 is for 20-byte IPMI 2.0 passwords. Note that setting the session limit to zero means there is no session limit. Also note that some systems have a bug where the session limit is not optional (as the spec says it is). If you get C7 errors back from this command, you will have to always specify the session limit. Note that you must enable the user for it to work, but there seems to be no way to get if the user is enabled or not. Response:

```
User Info Set: <mc>
```

### sel
Commands dealing with the system event log. Note that there is no info command.

list <domain> - The list command is unique in this object, so it is specified explicitly here. List the local copy of the system event log for the entire domain.

Response:

```
Domain

  Name: <domain>

  Entries: <integer>

  Slots in use: <integer>

  Event

    **EVENT INFO**

   .

   .
```

mc_list <domain> - List the local copy of the system event log on the given MC.

Response:

```
MC

  Name: <mc>

  Entries: <integer>

  Slots in use: <integer>

  Event

    **EVENT INFO**

   .

   .
```

delete <mc> <record #> - Delete the given event number from the SEL

Response:

```
Event deleted

  MC: <mc>

  Record: <integer>
```

add <mc> <type> <13 bytes of data> - Add the event data to the SEL.

Response:

```
MC

  Name: <mc>

  Record ID: <integer>
```

clear <domain> - clear the system event log

Response:

```
SEL Clear done: <domain>
```

### con
Commands dealing with connections.

activate <connection> - Activate the given connection

Response:

```
Connection activated: <connection>
```

### pet
Commands dealing with platform event traps.

new <domain> <connection> <channel> <ip addr> <mac_addr> <eft selector> <policy num> <apt selector> <lan dest selector> - Set up the domain to send PET traps from the given connection to the given IP/MAC address over the given channel.

Response:

```
PET Created: <pet>
```

mcnew <mc> <channel> <ip addr> <mac_addr> <eft selector> <policy num> <apt selector> <lan dest selector> - Set up the domain to send PET traps from the given connection to the given IP/MAC address over the given channel. This takes an MC instead of a connection.

Response:

```
PET Created: <pet>
```

close <pet> - Close the pet.

Response:

```
PET destroyed: <pet>
```

### pef
commands dealing with platform even filters. These are basically connections to the PEF configuration parameters in an MC. You use a pef to fetch a pef config, which you can then modify and write back to the MC. Note that when you get a pef config, you claim a lock on the MC that must be unlocked.

new <mc> - Create a pef for the given MC.

Response:

```
PEF: <pef>
```

unlock_mc <mc> - Unlock the PEF lock on the given MC.

Response:

```
PEF unlocked: <mc>
```

close <pef> - Free the given pef

Response:

```
PEF destroyed: <pef>
```

### pef config
Commands dealing with PEF configurations. These are the actual PEF data items.

get <pef> - Fetch the pef data items from the pef and create a pef config.

Response:

```
PEF Config

  Name: <pef config>

  **PEF CONFIG**
```

update <pef config> <parm> [selector] <value> - Set the given parameter in the pef config to the given value. If the parameter has a selector of some type, the selector must be given, otherwise no selector should be given.

Response:

```
PEF config updated: <pef config>
```

set <pef> <pef config> - Write the pef data back to the pef. Note that this must be the same pef used to create the config.

Response:

```
PEF config set: <pef config>
```

unlock <pef> <pef config> - Unlock the lock in the MC and mark the pef config as unlocked.

Response:

```
PEF config unlocked: <pef config>
```

close <pef config> - Free the pef config.

Response:

```
PEF config destroyed: <pef config>
```

### lanparm
Commands dealing with lanparms. These are basically connections to the LAN configuration parameters in an MC. You use a lanparm to fetch a lanparm config, which you can then modify and write back to the MC. Note that when you get a lanparm config, you claim a lock on the MC that must be unlocked.

new <mc> <channel> - Create a lanparm for the given MC and channel.

Response:

```
LANPARM: <lanparm>
```

unlock_mc <mc> <channel> - Unlock the lanparm lock on the given MC and channel.

Response:

```
LANPARM unlocked: <mc>
```

close <lanparm> - Free the given lanparm

Response:

```
LANPARM destroyed: <lanparm>
```

### lanparm config
Commands dealing with lanparm configurations. These are the actual lanparm data items.

get <lanparm> - Fetch the lanparm data items from the lanparm and create a lanparm config.

Response:

```
LANPARM Config

  Name: <lanparm config>

  **LANPARM CONFIG**
```

set <lanparm> <lanparm config> - Write the lanparm data back to the lanparm. Note that this must be the same lanparm used to create the config.

Response:

```
LANPARM config set: <lanparm config>
```

unlock <lanparm> <lanparm config> - Unlock the lock in the MC and mark the lanparm config as unlocked.

Response:

```
LANPARM config unlocked: <lanparm config>
```

close <lanparm config> - Free the lanparm config.

Response:

```
LANPARM config destroyed: <lanparm config>
```

## OTHER COMMANDS
A few general commands exist.

evinfo <bool> - Turn on or off dumping object information when an event comes in. This is false by default.

debug <type> <bool> - Turn the given debugging type on or off

## EVENTS
The command language will output events to the console when they happen. Events all occur in the format:

```
  Event

    **EVENT INFO**
```

The event info varies on the type of events. The defined events are listed below. Note that the output of some events depends on the setting of the evinfo command; the information about the object itself may or may not be output.

Some events have another event container; this is the IPMI event that caused the event to be output.

The following event is output when the domain is completely up and operational and finished all it SDR, FRU, and bus scans:

```
  EVENT

    Object Type: Domain

    Name: <domain>

    Operation: Domain fully up

    Connection Number: <integer>

    Port Number: <integer>

    Any Connection Up: <bool>

    Error: <integer>
```

The following comes out when domain connection infomration changes:

```
  EVENT

    Object Type: Domain

    Name: <domain>

    Operation: Connection Change
```

The following comes out when domains are added:

```
  EVENT

    Object Type: Domain

    Name: <domain>

    Operation: Add

    %**DOMAIN INFO**
```

The following comes out when domains are destroyed:

```
  EVENT

    Object Type: Domain

    Name: <domain>

    Operation: Delete
```

The following comes out when the domain gets an event that does not have a handler:

```
  EVENT

    Object Type: Event

    **EVENT INFO**
```

The following comes out when an entity is added:

```
  EVENT

    Object Type: Entity

    Name: <entity>

    Operation: Add

    %**ENTITY INFO**
```

The following comes out when an entity is deleted:

```
  EVENT

    Object Type: Entity

    Name: <entity>

    Operation: Delete
```

The following comes out when an entity is changed:

```
  EVENT

    Object Type: Entity

    Name: <entity>

    Operation: Change

    %**ENTITY INFO**
```

The following comes out when an entity's FRU is added:

```
  EVENT

    Object Type: Entity FRU

    Name: <entity>

    Operation: Add

    %**FRU INFO**
```

The following comes out when an entity's FRU is deleted:

```
  EVENT

    Object Type: Entity FRU

    Name: <entity>

    Operation: Delete
```

The following comes out when an entity's FRU is changed:

```
  EVENT

    Object Type: Entity FRU

    Name: <entity>

    Operation: Change

    %**FRU INFO**
```

The following comes out when an entity's presence changes:

```
  EVENT

    Object Type: Entity

    Name: <entity>

    Operation: Presence Change

    Present: <bool>

    %Event

      **EVENT INFO**
```

The following comes out when an entity's hot-swap state changes:

```
  EVENT

    Object Type: Entity

    Name: <entity>

    Operation: Hot-Swap Change

    Last State: <hot-swap state>

    State: <hot-swap state>

    %Event

      **EVENT INFO**
```

The following comes out when an MC is added:

```
  EVENT

    Object Type: MC

    Name: <mc>

    Operation: Add

    %**MC INFO**
```

The following comes out when an MC is removed:

```
  EVENT

    Object Type: MC

    Name: <mc>

    Operation: Delete
```

The following comes out when an MC is changed:

```
  EVENT

    Object Type: MC

    Name: <mc>

    Operation: Change

    %**MC INFO**
```

The following comes out when an MC changes active state:

```
  EVENT

    Object Type: MC

    Name: <mc>

    Operation: Active Changed

    Active: <bool>
```

The following comes out when a discrete sensor gets an event:

```
  EVENT

    Object Type: Sensor

    Name: <sensor>

    Operation: Event

    Offset: <integer>

    Direction: assertion | deassertion

    Severity: <integer>

    Previous Severity: <integer>

    %Event

      **EVENT INFO**
```

The following comes out when a threshold sensor gets an event:

```
  EVENT

    Object Type: Sensor

    Name: <sensor>

    Operation: Event

    Threshold: <threshold>

    High/Low: going-high | going-low

    Direction: assertion | deassertion

    %Value: <double>

    %Raw Value: <integer>

    %Event

      **EVENT INFO**
```

The following comes out when a sensor is added:

```
  EVENT

    Object Type: Sensor

    Name: <sensor>

    Operation: Add

    %**SENSOR INFO**
```

The following comes out when a sensor is deleted:

```
  EVENT

    Object Type: Sensor

    Name: <sensor>

    Operation: Delete
```

The following comes out when a sensor is changed:

```
  EVENT

    Object Type: Sensor

    Name: <sensor>

    Operation: Change

    %**SENSOR INFO**
```

The following comes out when a control gets an event:

```
  EVENT

    Object Type: Control

    Name: <control>

    Operation: Event

    Value

      Number: <integer>

      Value: <integer>

    %Event

      **EVENT INFO**
```

The following comes out when a control is added:

```
  EVENT

    Object Type: Control

    Name: <control>

    Operation: Add

    %**CONTROL INFO**
```

The following comes out when a control is deleted:

```
  EVENT

    Object Type: Control

    Name: <control>

    Operation: Delete
```

The following comes out when a control is changed:

```
  EVENT

    Object Type: Control

    Name: <control>

    Operation: Change

    %**CONTROL INFO**
```

## OBJECT INFO
Many of the command responses and events contain information about an objects. The definitions of this information output is done here.

### **EVENT INFO**

```
  MC: <mc>

  Record ID: <integer>

  Event type: <integer>

  Timestamp: <integer>

  Data: <data bytes>
```

### **DOMAIN INFO**

```
  Type: <domain type>

  GUID: <hex string>

  SEL Rescan Time: <time>

  IPMB Rescan Time: <time>
```

### **ENTITY INFO**

```
  Type: unknown | mc | fru | generic

  Present: <bool>

  Presence sensor always there: <bool>

  Hot swappable: <bool>

  %Supports managed hot swap: <bool>

  %Parents

    Name: <entity>

    Name: <entity>

     .

     .

  %Children

    Name: <entity>

    Name: <entity>

     .

     .

  %Physical Slot: <integer>

  %Id: <string>

  Entity ID String: <string>
```

Note that Parents and Children fields will not be present if the entity has no parents or children. Each entity type except unknown will have its own output info. These are:

mc

```
  Channel: <channel>

  LUN: <lun>

  OEM: <oem field from SDR>

  Slave Address: <ipmb>

  ACPI_system_power_notify_required: <bool>

  ACPI_device_power_notify_required: <bool>

  controller_logs_init_agent_errors: <bool>

  log_init_agent_errors_accessing: <bool>

  global_init: <bool>

  chassis_device: <bool>

  bridge: <bool>

  IPMB_event_generator: <bool>

  IPMB_event_receiver: <bool>

  FRU_inventory_device: <bool>

  SEL_device: <bool>

  SDR_repository_device: <bool>

  sensor_device: <bool>
```

fru

```
  Channel: <channel>

  LUN: <lun>

  OEM: <oem field from SDR>

  Slave Address: <ipmb>

  access_address: <ipmb>

  private_bus_id: <integer>

  device_type: <integer>

  device_modifier: <integer>

  is_logical_fru: <bool>

  fru_device_id: <integer>
```

generic

```
  Channel: <channel>

  LUN: <lun>

  OEM: <oem field from SDR>

  access_address: <ipmb>

  private_bus_id: <integer>

  device_type: <integer>

  device_modifier: <integer>

  slave_address: <ipmb>

  address_span: <integer>
```

### **MC INFO**

```
  Active: <bool>

  GUID: <hex string>

  SEL Rescan Time: <integer>

  provides_device_sdrs: <bool>

  device_available: <bool>

  chassis_support: <bool>

  bridge_support: <bool>

  ipmb_event_generator: <bool>

  ipmb_event_receiver: <bool>

  fru_inventory_support: <bool>

  sel_device_support: <bool>

  sdr_repository_support: <bool>

  sensor_device_support: <bool>

  device_id: <ipmb>

  device_revision: <integer>

  fw_revision: <integer>.<integer>

  version: <integer>.<integer>

  manufacturer_id: <integer>

  product_id: <integer>

  aux_fw_revision: <integer> <integer> <integer> <integer>
```

### *SENSOR INFO**

```
  LUN: <integer>

  Number: <integer>

  Event Reading Type: <integer>

  Event Reading Type Name: one of:

           unspecified threshold discrete_usage discrete_state

           discrete_predictive_failure discrete_limit_exceeded

           discrete_performance_met discrete_severity discrete_device_presence

           discrete_device_enable discrete_availability discrete_redundancy

           discrete_acpi_power

  Type: <integer>

  Type Name: <sensor type (a generic string)>

  %Direction: input | output

  %Event Support: per state | entire sensor | global

  Init Scanning: <bool>

  Init Events: <bool>

  Init Thresholds: <bool>

  Init Hysteresis: <bool>

  Init Type: <bool>

  Init Power Up Events: <bool>

  Init Power Up Scanning: <bool>

  Ignore If No Entity: <bool>

  Auto Rearm: <bool>

  OEM1: <integer>

  Id: <string>
```

For threshold sensors, the following exist:

```
  Threshold Access: none | readable | settable | fixed

  Threshold

    Name: <threshold>

    Readable: <bool>

    Settable: <bool>

    Supports: going high assertion | going low assertion

              | going high deassertion | going low deassertion

   .

   .

  Hysteresis Support: none | readable | settable | fixed

  %Nominal Reading: <float>

  %Normal Max: <float>

  %Normal Min: <float>

  %Sensor Max: <float>

  %Sensor Min: <float>

  Base Unit: <integer>

  Base Unit Name: <string>

  %Rate Unit: <integer>

  %Rate Unit Name: <string>

  %Modifier Use: / | *

  %Modifier Unit: <integer>

  %Modifier Unit Name: <string>
```

For discrete sensors, the following exist:

```
  Event

    Offset: <integer>

    Supports: assertion | deassertion

   .

   .
```

### **CONTROL INFO**

```
  Type: <control type>

  Generates Events: <bool>

  Settable: <bool>

  Readable: <bool>

  Num Values: <integer>

  Id: <string>
```

Controls of type light that are set with settings have the following:

```
  Set with: settings

  Local Control: <bool>

  Color: <color>

   .

   .
```

One color is listed for each supported color Controls of type light that are set with transitions have the following:

```
  Light

    Number: <integer>

    Num Values: <integer>

    Value

      Number: <integer>

      Num Transitions: <integer>

      Transition

        Number: <integer>

        Color: <color>

        Time: <integer>

       .

       .

     .

     .
```

Controls of type identifier have the following:

```
  Max Length: <integer>
```

### **FRU INFO**

```
  Name: <fru>

  record

    Name: <name>

    Type: binary | ascii | unicode | integer

    %Number: <integer>

    Data: data depending on type

   .

   .

  Multi-record

    Number: <integer>

    Type: binary | ascii | unicode

    Data: <data in the above format>

   .

   .
```

### **LANPARM CONFIG**

```
  support_auth_oem: <bool>

  support_auth_straight: <bool>

  support_auth_md5: <bool>

  support_auth_md2: <bool>

  support_auth_none: <bool>

  ip_addr_source: <integer>

  num_alert_destinations: <integer>

  %ipv4_ttl: <integer>

  %ipv4_flags: <integer>

  %ipv4_precedence: <integer>

  %ipv4_tos: <integer>

  %ip_addr: <ip addr>

  %mac_addr: <mac addr>

  %subnet_mask: <ip addr>

  %primary_rmcp_port <integer>

  %secondary_rmcp_port <integer>

  %bmc_generated_arps: <bool>

  %bmc_generated_garps: <bool>

  %garp_interval: <integer>

  %default_gateway_ip_addr: <ip addr>

  %default_gateway_mac_addr: <mac addr>

  %backup_gateway_ip_addr: <ip addr>

  %backup_gateway_mac_addr: <mac addr>

  community_string: <string>

  User

    Name: callback

    enable_auth_oem: <bool>

    enable_auth_straight: <bool>

    enable_auth_md5: <bool>

    enable_auth_md2: <bool>

    enable_auth_none: <bool>

  User

    Name: user

    enable_auth_oem: <bool>

    enable_auth_straight: <bool>

    enable_auth_md5: <bool>

    enable_auth_md2: <bool>

    enable_auth_none: <bool>

  User

    Name: operator

    enable_auth_oem: <bool>

    enable_auth_straight: <bool>

    enable_auth_md5: <bool>

    enable_auth_md2: <bool>

    enable_auth_none: <bool>

  User

    Name: admin

    enable_auth_oem: <bool>

    enable_auth_straight: <bool>

    enable_auth_md5: <bool>

    enable_auth_md2: <bool>

    enable_auth_none: <bool>

  User

    Name: oem

    enable_auth_oem: <bool>

    enable_auth_straight: <bool>

    enable_auth_md5: <bool>

    enable_auth_md2: <bool>

    enable_auth_none: <bool>

  Alert Destination

    Number: <integer>

    alert_ack: <bool>

    dest_type: <integer>

    alert_retry_interval: <integer>

    max_alert_retries: <integer>

    dest_format: <integer>

    gw_to_use: <integer>

    dest_ip_addr: <ip addr>

    dest_mac_addr: <mac addr>

   .

   .
```

### **PEF CONFIG**

```
  alert_startup_delay_enabled: <bool>

  startup_delay_enabled: <bool>

  event_messages_enabled: <bool>

  pef_enabled: <bool>

  diagnostic_interrupt_enabled: <bool>

  oem_action_enabled: <bool>

  power_cycle_enabled: <bool>

  reset_enabled: <bool>

  power_down_enabled: <bool>

  alert_enabled: <bool>

  %startup_delay: <integer>

  %alert_startup_delay: <integer>

  guid_enabled: <bool>

  guid_val: <guid>

  num_event_filters: <integer>

  num_alert_policies: <integer>

  num_alert_strings: <integer>

  Event Filter

    Number: <integer>

    enable_filter: <bool>

    filter_type: <integer>

    diagnostic_interrupt: <bool>

    oem_action: <bool>

    power_cycle: <bool>

    reset: <bool>

    power_down: <bool>

    alert: <bool>

    alert_policy_number: <integer>

    event_severity: <integer>

    generator_id_addr: <integer>

    generator_id_channel_lun: <integer>

    sensor_type: <integer>

    sensor_number: <integer>

    event_trigger: <integer>

    data1_offset_mask: <integer>

    data1_mask: <integer>

    data1_compare1: <integer>

    data1_compare2: <integer>

    data2_mask: <integer>

    data2_compare1: <integer>

    data2_compare2: <integer>

    data3_mask: <integer>

    data3_compare1: <integer>

    data3_compare2: <integer>

   .

   .

  Alert Policy

    Number: <integer>

    policy_num: <integer>

    enabled: <bool>

    policy: <integer>

    channel: <integer>

    destination_selector: <integer>

    alert_string_event_specific: <bool>

    alert_string_selector: <integer>

   .

   .

  Alert String

    event_filter: <integer>

    alert_string_set: <integer>

    alert_string: <string>

   .

   .
```

### **CONNECTION INFO**

```
  Active: <bool>

  Up: <bool>

  Port

    Number: <integer>

    Info: <info string>

    Up: <bool>

   .

   .
```

### **PEF INFO**

```
  MC: <mc>
```

### **PET INFO**

```
  MC: <mc>

  Channel: <channel>

  IP Address: <ip address>

  MAC Address: <mac address>

  EFT Selector: <eft selector>

  Policy Number: <policy number>

  APT Selector: <apt selector>

  LAN Dest Selector: <lan dest selector>
```

### **LANPARM INFO**

```
  MC: <mc>

  Channel: <integer>
```

## SEE ALSO
ipmish(1)

## KNOWN PROBLEMS
None

## AUTHOR
Corey Minyard <cminyard@mvista.com>


title: openipmi_conparms(7)

summary: Connection parmeters for OpenIPMI

text:
# openipmi_conparms(7)

## NAME
openipmi_cmdparms - Connection parmeters for OpenIPMI

## SYNOPSIS
smi smi-num

lan [-U username] [-P password] [-p[2] port] [-A authtype] [-L privilege] [-s] [-Ra auth alg] [-Ri integ alg] [-Rc conf algo] [-Rl] [-Rk bmc key] [-H hackname] host [ host]

## DESCRIPTION
The connection parameters for OpenIPMI vary depending on the connection type. This document describes the standard connection types; others may be available from OEMs.

## OPTIONS
smi-num

The SMI interface for the local connection. There may be more than one BMC connection on a system and they are generally numbered, like /dev/ipmi0, /dev/ipmi1, etc.

-U username

Use the given username for the LAN connection. If none is given, then no username is used.

-P password

The password to use for the connection. If none is given, the user is assumed to have an empty password

-p[2] port

The UCP port to connect to. This defaults to the standard 623 port, so it is not necessary unless a special port is required. Note that since you can have two connections (hosts), -p is for the first host and -p2 is for the second host.

-A authtype

The authentication type to use, one of rmcp+, md5, md2, straight, or none. If you don't supply this, the most secure one available is chosen, in the order given in the previous list.

-L privilege

The privilege to use for the connection. Lower privileges cannot execute some commands. Privileges are: callback, user, operator, admin, and oem. The default is admin.

-Ra authentication algorithm

Set the RMCP+ authentication algorithm to use. Options are: bmcpick, rakp_none, rakp_hmac_sha1, and rakp_hmac_md5. The bmcpick option is used by default, which means the BMC picks the algorithm it wants to use.

-Ri integrity algorithm

The RMCP+ integrity algorithm to use. This ensures that the data has not be altered between the sender and receiver. Valid options are: bmcpick, none, hmac_sha1, hmac_md5, and md5. The bmcpick option is used by default, which means the BMC picks the algorithm it wants to use.

-Rc confidentiality algorithm

The RMCP+ confidentiality (encryption) algorithm to use. This keeps evesdroppers from seeing the data. Valid values are: bmcpick, aes_cbc_128, xrc4_128, and xrc_40. The bmcpick option is used by default, which means the BMC picks the algorithm it wants to use.

-Rl

If this is specified, the username is looked up using the privilege level along with the username. This allows the same name to have different passwords with different privilege levels.

-Rk BMC Key

If the system requires two-key lookups, this specifies the second key (the BMC key) to use. This is ignored if two-key lookups are not enabled by the BMC.

-H hackname

Well, it always happens. Things in the field don't work quite like they are supposed to. There was some vagueness in the first IPMI specs and different vendors interpreted RMCP+ in different ways. This allows different options to be supported. Try different hacks if your RMCP+ systems don't authenticate properly. These are:

rakp3_wrong_rolem

Some systems use the incorrect Role(m) field in a specific authentication message (the RAKP3 message). This is a common problem.

rmcpp_integ_sik

The original IPMI 2.0 spec specified the incorrect key to use for the integrity key. This forces use of the Session Initiation Key. The default is to use K(1)

-s

Make two connections to the BMC. This means the BMC has two different IP addresses/ports that are equivalent. If this is specified, a second host must be supplied. This is not the same as two connections to two different BMCs. This must be a connection to the same BMC.

host

The IP address (either by name lookup or specified directly) to connect to. If the -s is specified, two hosts must be supplied.

The -Ra, -Ri, -Rc, -Rk and -Rl options only apply to RMCP+ connections and will be ignored if the connection does not support RMCP+ or if a non-RMCP+ authentication type is specified.

## SEE ALSO
ipmish(8), openipmicmd(8), solterm(1)

## KNOWN PROBLEMS
This is excessively complicated, but the defaults should be good.

## AUTHOR
Corey Minyard <cminyard@mvista.com>


title: openl2tp(7)

summary: General documentation

text:
# openl2tp(7)

## NAME
openl2tp - General documentation

## SYNOPSIS
This document describes the general features of OpenL2TP, a dual-licensed, open-source implementation of L2TP for Linux.

OpenL2TP is ideal for use in any of the following environments:-

- as an L2TP VPN service for deployment on servers at the workplace, providing L2TP VPN access for home workers.

- as a component in commercial Embedded Linux systems, such as home gateways or even big telecommunications switches.

- as an L2TP client for desktop users.

## PROTOCOL OVERVIEW
L2TP was designed by the IETF (Internet Engineering Task Force, the internet standards body) to tunnel one or more PPP sessions through an IP tunnel across an IP network. It utilizes two types of messages, control messages and data messages. Control messages are used in the establishment, maintenance and clearing of tunnels and sessions. Data messages are used to encapsulate PPP frames being carried over the tunnel. Control messages utilize a reliable control channel within L2TP to guarantee delivery. Data messages are not retransmitted when packet loss occurs.

When two L2TP peers have established a tunnel, sessions may be added to the tunnel. A tunnel may carry up to 65535 sessions. Control message exchanges are used to setup each L2TP session. When an L2TP session is in place, PPP data packets may be passed over the (unreliable) data channel of the session. Thus data packets are encapsulated first by an L2TP header and then a packet transport such as UDP, Frame Relay, ATM, etc.

```
   +-------------------+

   | PPP Frames        |

   +-------------------+    +-----------------------+

   | L2TP Data Messages|    | L2TP Control Messages |

   +-------------------+    +-----------------------+

   | L2TP Data Channel |    | L2TP Control Channel  |

   | (unreliable)      |    | (reliable)            |

   +------------------------------------------------+

   |      Packet Transport (UDP, FR, ATM, etc.)     |

   +------------------------------------------------+
	Diagram reproduced from RFC2661
```

### L2TP Access Concentrator (LAC)
The LAC takes PPP sessions from ingress interfaces, which may be regular modems, ATM (PPPoA), Frame Relay (PPPoFR) or ethernet (PPPoE) interfaces and tunnels them through L2TP tunnels. The LAC might create a new tunnel on-demand for the PPP session or it might choose to use an existing L2TP tunnel if it already exists.

In the simplest case, the PPP client and LAC are located on the same host and only one PPP session is used per L2TP tunnel. Some L2TP implementations, most notably Microsoft's, have this limitation.

### L2TP Network Server (LNS)
The LNS is typically the server side of an L2TP connection. It accepts requests from the network to create new tunnels or add new sessions to tunnels. The LNS may terminate the PPP sessions locally or it may forward them via egress PPP interfaces.

## FEATURE SUMMARY
OpenL2TP is a complete implementation of RFC2661 - Layer Two Tunneling Protocol, Version 2. Key features are:-

- Operation as both LAC and LNS simultanesously is supported. A single server may be a LAC for some tunnels and a LNS for others.

- Incoming and outgoing tunnels and sessions are supported.

- Multiple tunnels and multiple sessions in those tunnels are supported. The maximum number of tunnels and sessions is limited only by available system memory (max 65535 tunnels and 65535 sessions per tunnel) or by system and user-configured limits.

- All four session types are supported, i.e. LAC/LNS Incoming/Outgoing Calls.

- Multiple tunnels between the same two L2TP hosts is supported.

- Tunnel, session and PPP parameters may be defined in named profiles, simplifying the management interface and allowing specific parameter values to be used for specific incoming tunnels (those created by remote request over the network).

- Is able to parse and record all standard L2TP AVPs defined in RFC2661. It checks that all required AVPs are present in each message and generates error log messages if unexpected AVPs are seen.

- Control messages are handled by a userland daemon, openl2tpd. All L2TP data packets are handled by the kernel.

- Trace messages optionally logged using syslog can be enabled/disabled at system, tunnel and session levels. Thus to debug problems on a busy system, tracing can be safely enabled only for specific entities without flooding the system with messages from other uninteresting entities.

- Management interface uses Sun RPC, making OpenL2TP particularly suitable for embedded chassis environments such as telco systems. No config files to worry about!

- Bundled with an intuitive command-line management application that uses TAB syntax completion, command history and context sensitive help.

- Employs a plugin architecture to allow third parties to easily extend or integrate OpenL2TP with other software, e.g. PPP, RADIUS, B-RAS etc etc. Includes a plugin for interfacing to pppd(8) but other PPP implementations may be used if desired via a plugin.

- Supports automatic IP address assignment from local address pools if other address allocation mechanisms (e.g. RADIUS) are not configured. Use ippoold(8).

- Locally created tunnels may optionally be designated persistent, causing them to try to recreate themselves should the tunnel fail for some reason. Any locally created sessions in persistent tunnels are also automatically restored if/when the tunnel restablishes itself. This is useful if openl2tpd is used as an L2TP client.

- Interoperates with Cisco IOS 12.2 and Microsoft W2K/XP.

## PROFILES
Profiles allow a set of tunnel, session or PPP parameters to be configured and then referred to by name. For tunnels and sessions created by a local administrator, profiles simply offer a convenient shorthand for specifying several parameters in one go. However, profiles are most useful to specify parameters to be used in the future when L2TP tunnels or sessions are created by remote request over the network.

The following profile types exist:-

TUNNEL PROFILE

Provides a named set of L2TP tunnel parameters which may be used when creating tunnels locally (by specifying the tunnel profile name when the tunnel is created) or when tunnels are created by remote request.

SESSION PROFILE

Provides a named set of L2TP session parameters which may be used when creating sessions locally (by specifying the session profile name when the session is created) or when sessions are created by remote request.

PPP PROFILE

Provides a named set of PPP parameters which are to be used when creating PPP connections in L2TP sessions.

PEER PROFILE

Identifies parameters to be used when connecting to an L2TP peer. Peers are identified by name or by IP address / netmask. The peer profile specifies default tunnel, session and PPP profile names which are to be used when communicating with the peer.

An administrator may create as many profiles as desired. The naming of profiles is scoped by profile type; it is possible to create a tunnel profile called one and a session profile called one, for example.

The profile name default is reserved; it is the name of default profiles which are used by the system when no other profile can be found.

Every parameter of a tunnel or session profile may be specified when a tunnel or session is created by a local administrator. If, therefore, OpenL2TP is being used as a simple, manually configured L2TP client, tunnel and session profiles aren't strictly necessary; the administrator just gives values for all non-default parameters when creating the tunnel or session.

When new L2TP tunnels, L2TP sessions or PPP connections are created, parameter values for any parameters not specified in the create request are derived from default profiles. These default profiles are automatically created by the system; their parameter values may be modified but the default profiles cannot be deleted. Default profiles thus provide a convenient way to override the default behavior of OpenL2TP.

For incoming tunnel, session and PPP setup requests, parameters are derived from tunnel, session and PPP profiles named in the peer profile that matches the incoming peer. Thus, to configure a server to accept incoming tunnel requests from host X, using a shared password Y, the local administrator would do the following:-

- create a tunnel profile and specify the tunnel password, authentication mode and any other L2TP tunnel parameters to be used for the peer.

- create a peer profile, giving it the same name as the hostname of the remote peer. Specify the tunnel profile name of the tunnel profile previously created.

If multiple tunnel peers share the same password, the same tunnel profile may be used for each peer.

Note that for further flexibility, tunnel profiles allow the session profile and PPP profile to be named. Thus, when a new L2TP session is created in a tunnel, if a session profile isn't specified in the request, its session parameters are derived from the session profile called out via the tunnel profile, or via the session profile named in the peer profile if the tunnel profile did not include a session profile name. Similarly, PPP parameters are derived from the PPP profile specified in the request, or in the session profile, or in the tunnel profile or in the peer profile. This feature is known as profile inheritance.

## SECURE TUNNEL ESTABLISHMENT
The L2TP standard, documented in RFC2661, provides mechanisms for secure tunnel establishment.

Tunnels may optionally be protected using a shared password (secret) which must be configured at both LAC and LNS. This may be used to prevent unwanted tunnels being created; the LAC or LNS sends a challenge to the peer using the shared tunnel password and expects a valid response before allowing the new tunnel to be created.

To prevent hackers from eavesdropping on L2TP protocol packets, some protocol fields (called Attribute Value Pairs, or AVPs) in L2TP protocol messages may be hidden (encrypted). This so-called AVP hiding may be enabled when the tunnel is created. Either or both LAC and LNS may use AVP hiding in L2TP messages that it sends.

OpenL2TP provides Simple and Challenge tunnel authentication modes for incoming tunnels.

SIMPLE

accepts the tunnel only if a matching peer profile can be found for the peer; a shared tunnel password is not required. Thus, by creating one or more peer profiles, an operator determines the peer host names and/or IP address ranges of permitted remote peers without needing to use passwords..

CHALLENGE

accepts the tunnel only if both SIMPLE authentication succeeds and an L2TP challenge is requested by the peer. This is the most secure mode, as it enforces the use of L2TP Challenge and Peer Profiles to identify a set of permitted remote L2TP peers.

By default, neither SIMPLE nor CHALLENGE authentication mode is enabled; L2TP requests are accepted from any remote peer.

## L2TP LINUX KERNEL DRIVER
In order to exchange data packets over an L2TP session, the bundled PPP-over-L2TP Linux device driver must be installed. It may be built statically into the kernel or as a loadable binary module.

The L2TP server will partially operate without the L2TP kernel support in place; L2TP tunnels and sessions are created as normal, but no data can be passed through the L2TP session. This may be useful for testing the protocol but it isn't useful for much else; indeed, many third party L2TP implementations such as Cisco will close the session when it fails to do PPP link setup.

## MANAGEMENT INTERFACE
OpenL2TP departs from UNIX tradition in that it does not use config files. Instead it uses Sun RPC (Remote Procedure Call) to provide an extensive binary API to L2TP servers over a network.

Sun RPC is used in preference to proprietary message passing over sockets for several reasons:-

- RPC handles all architecture differences. It is possible to run a L2TP control application on, say an Intel Pentium CPU to control several L2TP servers running on PowerPC CPUs, for example. It is also ideal for Linux Cluster environments.

- The management interface is defined in a Structured Definition Language from which C (or even Java) code can be generated. Therefore a single interface definition describes the application API. Readers interested in RPC should see rpc(3).

- RPC lends itself to several new network management technologies such as XML, SOAP, JAX and others.

For simple installations on a standard Linux workstation, the use of RPC could be seen as over-complicated and a security risk (since RPC requests can arrive over an IP network). Whilst this might be true, OpenL2TP is also targetted for easy deployment in commercial system chassis environments where CPUs on multiple boards in the chassis are controlled by other CPUs in the system. The ability to control OpenL2TP over a closed network makes for much easier integration into industrial solutions.

However, many installations will not need remote management capability so remote RPC requests are by default disabled. The L2TP server openl2tpd must be started with the -R command line switch to enable remote RPC.

It is recommended that when remote RPC is enabled, a firewall is used to protect the system from external attack.

## IPSEC
OpenL2TP can be used with or without IPSec. To use IPSec, make sure that racoon is installed (from http://ipsec-tools.sourceforge.net) and start openl2tpd with -p ipsec.so to use the IPSec plugin. This plugin tracks L2TP tunnel setups and installs rules in the IPSec Security Policy Database (SPD). Since this plugin tracks ephemeral port usage, OpenL2TP supports multiple L2TP/IPSec connections between the same IP peers. This allows configurations where there are multiple L2TP/IPSec clients behind a NAT gateway, connecting to a remote L2TP server.

To set up an L2TP/IPSec server with OpenL2TP, set up IPSec for the desired IPSec policies. An example racoon configuration file is provided in the OpenL2TP distribution to help get started. Add Security Policy Database (SPD) entries for the initial L2TP control connection (port 1701). When OpenL2TP is used with its ipsec plugin, additional policies are added on demand for actual IP addresses and ephemeral UDP ports, as tunnels are created and deleted. The following setkey command adds an SPD to allow an L2TP server to serve L2TP/IPSec clients from any remote IP addresses.

```
spdadd 0.0.0.0/0[1701] 0.0.0.0/0 udp -P in ipsec
	esp/transport//require;
```

Then start openl2tpd with its ipsec plugin.

```
openl2tpd -p ipsec.so
```

## INTEROPABILITY

### Microsoft Windows 2000 and Windows XP
•

By default, Microsoft L2TP uses IPSec for all L2TP tunnels. To disable IPSec on Microsoft systems, see

```
http://support.microsoft.com/default.aspx?scid=kb;en-us;q310109&sd=tech.
```

•

Microsoft L2TP clients negotiate a PPP MTU of only 1400 bytes. Duh!

### Cisco IOS 12.2

- Cisco does not handle hidden AVPs in the SCCRQ message. As a workaround, OpenL2TP turns off AVP hiding of all attributes in the SCCRQ, even if AVP hiding is enabled in the tunnel. Unlike Cisco, OpenL2TP can handle hidden AVPs in the SCCRQ message.

- Cisco advertises a Receive Window Size (RWS) of 800 by default which seems way too large -- RFC2661 says the default should be 10.

## UNIMPLEMENTED FEATURES
The L2TP specification includes a few optional features that are not currently implemented by OpenL2TP. These are:-

DATA PACKET REORDERING

Data packets optionally carry sequence numbers. Although these sequence numbers are never used to retransmit unacknowledged data packets, they may be used by the receiver to try to reorder out-of-sequence packets. Currently, OpenL2TP simply discards such packets.

PPP PROXY

PPP Proxy allows a LAC or LNS to shortcut PPP LCP negotiation by extracting PPP configuration messages and providing them to the peer with the L2TP session setup request. The peer passes this data to its PPP session and the two PPP sessions continue with PPP negotiation as if they were always directly connected. Although the OpenL2TP API supports it, proxy PPP requires major work in the standard UNIX PPP server application pppd(8) and Linux kernel. However, OpenL2TP already recognizes the PPP PROXY parameters of L2TP protocol messages and will report attributes that it receives from its peer using the current tunnel API. PPP PROXY is useful only in systems implementing some form of Broadband Remote Access Server (B-RAS).

PMTU DISCOVERY

Strictly speaking, PMTU Discovery is not called out in the L2TP specification. This mechanism allows a host to determine the MTU of the network path to its peer. Although it can be requested when a tunnel is created, it is currently unimplemented.

## LIMITATIONS
Although OpenL2TP is a comprehensive L2TP implementation, it does have some limitations. These are:-

- It creates one UDP socket per tunnel and a temporary socket (as needed) for kernel interaction. The maximum number of tunnels is therefore limited by the maximum number of file descriptors that a single process may have open (MAX_FILES). This is typically 1024 but may be adjusted using ulimit(3).

- It creates one PPPoL2TP socket per session. If pppd(8) is used for PPP, these file descriptors are opened by the pppd process, so don't add to the file descriptors used by openl2tpd. However, if all PPP sessions are controlled by a single PPP process using a third party PPP implementation, the maximum session count is again limited by MAX_FILES.

- If pppd(8) is used to provide PPP, one pppd process is spawned for each session. Although in virtual memory systems, the text segment (code) is shared between all instances of pppd, each process has its own data and heap. The heap alone can consume 1M of memory which can pose real problems to systems without swap space such as embedded systems.

- Internally, openl2tpd keeps lists of objects (tunnels, sessions, ppp, profiles etc) in linear linked lists. When the number of entries in its lists becomes large, system performance is degraded because it takes a long time to walk the lists to find contexts. This will be fixed in a later release.

- It is not possible to run two instances of openl2tpd on the same system because they will both try to register the same RPC service and one will fail.

## REPORTING BUGS
Please report bugs to <openl2tp-bugs@lists.sourceforge.net>.

## SEE ALSO
The following documents are also available in the OpenL2TP set:-

openl2tpd(8)

describes how to invoke openl2tpd which is the L2TP daemon.

openl2tp_rpc(4)

describes the RPC interface implemented by openl2tpd. This interface may be used by an RPC client application to control openl2tpd .

l2tpconfig(1)

describes the command line interface application which is bundled with OpenL2TP distribution. It is an RPC client application, implementing the interfaces documented in openl2tp_rpc(4).

ippoold(8)

an IP address pool manager.

openl2tpd.conf(5)

describes the syntax of a local configuration file which may be used instead of l2tpconfig to control the L2TP daemon.


package: openssl

title: EVP_ASYM_CIPHER-RSA(7ossl)

summary: RSA

text:
# EVP_ASYM_CIPHER-RSA(7ossl)

## NAME
EVP_ASYM_CIPHER-RSA - RSA Asymmetric Cipher algorithm support

## DESCRIPTION
Asymmetric Cipher support for the RSA key type.

### RSA Asymmetric Cipher parameters
"pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <UTF8 string>

The default provider understands these RSA padding modes in string form:

"none" (OSSL_PKEY_RSA_PAD_MODE_NONE)

"oaep" (OSSL_PKEY_RSA_PAD_MODE_OAEP)

"pkcs1" (OSSL_PKEY_RSA_PAD_MODE_PKCSV15)

"x931" (OSSL_PKEY_RSA_PAD_MODE_X931)

"pad-mode" (OSSL_ASYM_CIPHER_PARAM_PAD_MODE) <integer>

The default provider understands these RSA padding modes in integer form:

1 (RSA_PKCS1_PADDING)

3 (RSA_NO_PADDING)

4 (RSA_PKCS1_OAEP_PADDING)

5 (RSA_X931_PADDING)

See EVP_PKEY_CTX_set_rsa_padding(3) for further details.

"digest" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST) <UTF8 string>

"digest-props" (OSSL_ASYM_CIPHER_PARAM_OAEP_DIGEST_PROPS) <UTF8 string>

"mgf1-digest" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST) <UTF8 string>

"mgf1-digest-props" (OSSL_ASYM_CIPHER_PARAM_MGF1_DIGEST_PROPS) <UTF8 string>

"oaep-label" (OSSL_ASYM_CIPHER_PARAM_OAEP_LABEL) <octet string>

"tls-client-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>

See RSA_PKCS1_WITH_TLS_PADDING on the page EVP_PKEY_CTX_set_rsa_padding(3).

"tls-negotiated-version" (OSSL_ASYM_CIPHER_PARAM_TLS_CLIENT_VERSION) <unsigned integer>

See RSA_PKCS1_WITH_TLS_PADDING on the page EVP_PKEY_CTX_set_rsa_padding(3). See "Asymmetric Cipher Parameters" in provider-asym_cipher(7) for more information.

## SEE ALSO
EVP_PKEY-RSA(7), EVP_PKEY(3), provider-asym_cipher(7), provider-keymgmt(7), OSSL_PROVIDER-default(7) OSSL_PROVIDER-FIPS(7)

## COPYRIGHT
Copyright 2022 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_ASYM_CIPHER-SM2(7ossl)

text:
# EVP_ASYM_CIPHER-SM2(7ossl)

## NAME
EVP_ASYM_CIPHER-SM2 - SM2 Asymmetric Cipher algorithm support

## DESCRIPTION
Asymmetric Cipher support for the SM2 key type.

### SM2 Asymmetric Cipher parameters
"digest" (OSSL_ASYM_CIPHER_PARAM_DIGEST) <UTF8 string>

"digest-props" (OSSL_ASYM_CIPHER_PARAM_DIGEST_PROPS) <UTF8 string>

See "Asymmetric Cipher Parameters" in provider-asym_cipher(7).

## SEE ALSO
EVP_PKEY-SM2(7), EVP_PKEY(3), provider-asym_cipher(7), provider-keymgmt(7), OSSL_PROVIDER-default(7)

## COPYRIGHT
Copyright 2020 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-AES(7ossl)

summary: The AES EVP_CIPHER implementations

text:
# EVP_CIPHER-AES(7ossl)

## NAME
EVP_CIPHER-AES - The AES EVP_CIPHER implementations

## DESCRIPTION
Support for AES symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the FIPS provider as well as the default provider:

"AES-128-CBC", "AES-192-CBC" and "AES-256-CBC"

"AES-128-CBC-CTS", "AES-192-CBC-CTS" and "AES-256-CBC-CTS"

"AES-128-CFB", "AES-192-CFB", "AES-256-CFB", "AES-128-CFB1", "AES-192-CFB1", "AES-256-CFB1", "AES-128-CFB8", "AES-192-CFB8" and "AES-256-CFB8"

"AES-128-CTR", "AES-192-CTR" and "AES-256-CTR"

"AES-128-ECB", "AES-192-ECB" and "AES-256-ECB"

"AES-192-OFB", "AES-128-OFB" and "AES-256-OFB"

"AES-128-XTS" and "AES-256-XTS"

"AES-128-CCM", "AES-192-CCM" and "AES-256-CCM"

"AES-128-GCM", "AES-192-GCM" and "AES-256-GCM"

"AES-128-WRAP", "AES-192-WRAP", "AES-256-WRAP", "AES-128-WRAP-PAD", "AES-192-WRAP-PAD", "AES-256-WRAP-PAD", "AES-128-WRAP-INV", "AES-192-WRAP-INV", "AES-256-WRAP-INV", "AES-128-WRAP-PAD-INV", "AES-192-WRAP-PAD-INV" and "AES-256-WRAP-PAD-INV"

"AES-128-CBC-HMAC-SHA1", "AES-256-CBC-HMAC-SHA1", "AES-128-CBC-HMAC-SHA256" and "AES-256-CBC-HMAC-SHA256"

The following algorithms are available in the default provider, but not the FIPS provider:

"AES-128-OCB", "AES-192-OCB" and "AES-256-OCB"

"AES-128-SIV", "AES-192-SIV" and "AES-256-SIV"

"AES-128-GCM-SIV", "AES-192-GCM-SIV" and "AES-256-GCM-SIV"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## NOTES
The AES-SIV and AES-WRAP mode implementations do not support streaming. That means to obtain correct results there can be only one EVP_EncryptUpdate(3) or EVP_DecryptUpdate(3) call after the initialization of the context.

The AES-XTS implementations allow streaming to be performed, but each EVP_EncryptUpdate(3) or EVP_DecryptUpdate(3) call requires each input to be a multiple of the blocksize. Only the final EVP_EncryptUpdate() or EVP_DecryptUpdate() call can optionally have an input that is not a multiple of the blocksize but is larger than one block. In that case ciphertext stealing (CTS) is used to fill the block.

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7)

## HISTORY
The GCM-SIV mode ciphers were added in OpenSSL version 3.2.

## COPYRIGHT
Copyright 2021-2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-ARIA(7ossl)

summary: The ARIA EVP_CIPHER implementations

text:
# EVP_CIPHER-ARIA(7ossl)

## NAME
EVP_CIPHER-ARIA - The ARIA EVP_CIPHER implementations

## DESCRIPTION
Support for ARIA symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the default provider:

"ARIA-128-CBC", "ARIA-192-CBC" and "ARIA-256-CBC"

"ARIA-128-CFB", "ARIA-192-CFB", "ARIA-256-CFB", "ARIA-128-CFB1", "ARIA-192-CFB1", "ARIA-256-CFB1", "ARIA-128-CFB8", "ARIA-192-CFB8" and "ARIA-256-CFB8"

"ARIA-128-CTR", "ARIA-192-CTR" and "ARIA-256-CTR"

"ARIA-128-ECB", "ARIA-192-ECB" and "ARIA-256-ECB"

"AES-192-OCB", "AES-128-OCB" and "AES-256-OCB"

"ARIA-128-OFB", "ARIA-192-OFB" and "ARIA-256-OFB"

"ARIA-128-CCM", "ARIA-192-CCM" and "ARIA-256-CCM"

"ARIA-128-GCM", "ARIA-192-GCM" and "ARIA-256-GCM"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-default(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-BLOWFISH(7ossl)

summary: The BLOBFISH EVP_CIPHER implementations

text:
# EVP_CIPHER-BLOWFISH(7ossl)

## NAME
EVP_CIPHER-BLOWFISH - The BLOBFISH EVP_CIPHER implementations

## DESCRIPTION
Support for BLOWFISH symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the legacy provider:

"BF-ECB"

"BF-CBC"

"BF-OFB"

"BF-CFB"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-CAMELLIA(7ossl)

summary: The CAMELLIA EVP_CIPHER implementations

text:
# EVP_CIPHER-CAMELLIA(7ossl)

## NAME
EVP_CIPHER-CAMELLIA - The CAMELLIA EVP_CIPHER implementations

## DESCRIPTION
Support for CAMELLIA symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the default provider:

"CAMELLIA-128-CBC", "CAMELLIA-192-CBC" and "CAMELLIA-256-CBC"

"CAMELLIA-128-CBC-CTS", "CAMELLIA-192-CBC-CTS" and "CAMELLIA-256-CBC-CTS"

"CAMELLIA-128-CFB", "CAMELLIA-192-CFB", "CAMELLIA-256-CFB", "CAMELLIA-128-CFB1", "CAMELLIA-192-CFB1", "CAMELLIA-256-CFB1", "CAMELLIA-128-CFB8", "CAMELLIA-192-CFB8" and "CAMELLIA-256-CFB8"

"CAMELLIA-128-CTR", "CAMELLIA-192-CTR" and "CAMELLIA-256-CTR"

"CAMELLIA-128-ECB", "CAMELLIA-192-ECB" and "CAMELLIA-256-ECB"

"CAMELLIA-192-OFB", "CAMELLIA-128-OFB" and "CAMELLIA-256-OFB"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-default(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-CAST(7ossl)

summary: The CAST EVP_CIPHER implementations

text:
# EVP_CIPHER-CAST(7ossl)

## NAME
EVP_CIPHER-CAST - The CAST EVP_CIPHER implementations

## DESCRIPTION
Support for CAST symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the legacy provider:

"CAST-128-CBC", "CAST-192-CBC" and "CAST-256-CBC"

"CAST-128-CFB", "CAST-192-CFB", "CAST-256-CFB"

"CAST-128-ECB", "CAST-192-ECB" and "CAST-256-ECB"

"CAST-192-OFB", "CAST-128-OFB" and "CAST-256-OFB"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-CHACHA(7ossl)

summary: The CHACHA EVP_CIPHER implementations

text:
# EVP_CIPHER-CHACHA(7ossl)

## NAME
EVP_CIPHER-CHACHA - The CHACHA EVP_CIPHER implementations

## DESCRIPTION
Support for CHACHA symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the default provider:

"ChaCha20"

"ChaCha20-Poly1305"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-default(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-DES(7ossl)

summary: The DES EVP_CIPHER implementations

text:
# EVP_CIPHER-DES(7ossl)

## NAME
EVP_CIPHER-DES - The DES EVP_CIPHER implementations

## DESCRIPTION
Support for DES symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the FIPS provider as well as the default provider:

"DES-EDE3-ECB" or "DES-EDE3"

"DES-EDE3-CBC" or "DES3"

The following algorithms are available in the default provider, but not the FIPS provider:

"DES-EDE3-CFB8" and "DES-EDE3-CFB1"

"DES-EDE-ECB" or "DES-EDE"

"DES-EDE-CBC"

"DES-EDE-OFB"

"DES-EDE-CFB"

"DES3-WRAP"

The following algorithms are available in the legacy provider:

"DES-ECB"

"DES-CBC"

"DES-OFB"

"DES-CFB", "DES-CFB1" and "DES-CFB8"

"DESX-CBC"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-FIPS(7), OSSL_PROVIDER-default(7), OSSL_PROVIDER-legacy(7),

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-IDEA(7ossl)

summary: The IDEA EVP_CIPHER implementations

text:
# EVP_CIPHER-IDEA(7ossl)

## NAME
EVP_CIPHER-IDEA - The IDEA EVP_CIPHER implementations

## DESCRIPTION
Support for IDEA symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the legacy provider:

"IDEA-ECB"

"IDEA-CBC"

"IDEA-OFB" or "IDEA-OFB64"

"IDEA-CFB" or "IDEA-CFB64"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-NULL(7ossl)

summary: The NULL EVP_CIPHER implementation

text:
# EVP_CIPHER-NULL(7ossl)

## NAME
EVP_CIPHER-NULL - The NULL EVP_CIPHER implementation

## DESCRIPTION
Support for a NULL symmetric encryption using the EVP_CIPHER API. This is used when the TLS cipher suite is TLS_NULL_WITH_NULL_NULL. This does no encryption (just copies the data) and has a mac size of zero.

### Algorithm Name
The following algorithm is available in the default provider:

"NULL"

### Parameters
This implementation supports the following parameters:

Gettable EVP_CIPHER parameters

See "Gettable EVP_CIPHER parameters" in EVP_EncryptInit(3)

Gettable EVP_CIPHER_CTX parameters

"keylen" (OSSL_CIPHER_PARAM_KEYLEN) <unsigned integer>

"ivlen" (OSSL_CIPHER_PARAM_IVLEN and <OSSL_CIPHER_PARAM_AEAD_IVLEN) <unsigned integer>

"tls-mac" (OSSL_CIPHER_PARAM_TLS_MAC) <octet ptr>

See "PARAMETERS" in EVP_EncryptInit(3) for further information.

Settable EVP_CIPHER_CTX parameters

"tls-mac-size" (OSSL_CIPHER_PARAM_TLS_MAC_SIZE) <unsigned integer>

See "PARAMETERS" in EVP_EncryptInit(3) for further information.

## CONFORMING TO
RFC 5246 section-6.2.3.1

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-default(7)

## COPYRIGHT
Copyright 2023 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-RC2(7ossl)

summary: The RC2 EVP_CIPHER implementations

text:
# EVP_CIPHER-RC2(7ossl)

## NAME
EVP_CIPHER-RC2 - The RC2 EVP_CIPHER implementations

## DESCRIPTION
Support for RC2 symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the legacy provider:

"RC2-CBC", "RC2" or "RC2-128"

"RC2-40-CBC" or "RC2-40"

"RC2-64-CBC" or "RC2-64"

"RC2-ECB"

"RC2-CFB"

"RC2-OFB"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-RC4(7ossl)

summary: The RC4 EVP_CIPHER implementations

text:
# EVP_CIPHER-RC4(7ossl)

## NAME
EVP_CIPHER-RC4 - The RC4 EVP_CIPHER implementations

## DESCRIPTION
Support for RC4 symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the legacy provider:

"RC4"

"RC4-40"

"RC4-HMAC-MD5"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-RC5(7ossl)

summary: The RC5 EVP_CIPHER implementations

text:
# EVP_CIPHER-RC5(7ossl)

## NAME
EVP_CIPHER-RC5 - The RC5 EVP_CIPHER implementations

## DESCRIPTION
Support for RC5 symmetric encryption using the EVP_CIPHER API.

Disabled by default. Use the enable-rc5 configuration option to enable.

### Algorithm Names
The following algorithms are available in the legacy provider:

"RC5-CBC" or "RC5"

"RC5-ECB"

"RC5-OFB"

"RC5-CFB"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-SEED(7ossl)

summary: The SEED EVP_CIPHER implementations

text:
# EVP_CIPHER-SEED(7ossl)

## NAME
EVP_CIPHER-SEED - The SEED EVP_CIPHER implementations

## DESCRIPTION
Support for SEED symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the legacy provider:

"SEED-CBC" or "SEED"

"SEED-ECB"

"SEED-OFB" or "SEED-OFB128"

"SEED-CFB" or "SEED-CFB128"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-legacy(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_CIPHER-SM4(7ossl)

summary: The SM4 EVP_CIPHER implementations

text:
# EVP_CIPHER-SM4(7ossl)

## NAME
EVP_CIPHER-SM4 - The SM4 EVP_CIPHER implementations

## DESCRIPTION
Support for SM4 symmetric encryption using the EVP_CIPHER API.

### Algorithm Names
The following algorithms are available in the default provider:

"SM4-CBC:SM4"

"SM4-ECB"

"SM4-CTR"

"SM4-OFB" or "SM4-OFB128"

"SM4-CFB" or "SM4-CFB128"

"SM4-GCM"

"SM4-CCM"

"SM4-XTS"

### Parameters
This implementation supports the parameters described in "PARAMETERS" in EVP_EncryptInit(3).

## NOTES
The SM4-XTS implementation allows streaming to be performed, but each EVP_EncryptUpdate(3) or EVP_DecryptUpdate(3) call requires each input to be a multiple of the blocksize. Only the final EVP_EncryptUpdate() or EVP_DecryptUpdate() call can optionally have an input that is not a multiple of the blocksize but is larger than one block. In that case ciphertext stealing (CTS) is used to fill the block.

## SEE ALSO
provider-cipher(7), OSSL_PROVIDER-default(7)

## COPYRIGHT
Copyright 2021 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.


title: EVP_KDF-ARGON2(7ossl)

summary: The Argon2 EVP KDF implementation

text:
# EVP_KDF-ARGON2(7ossl)

## NAME
EVP_KDF-ARGON2 - The Argon2 EVP KDF implementation

## DESCRIPTION
Support for computing the argon2 password-based KDF through the EVP_KDF API.

The EVP_KDF-ARGON2 algorithm implements the Argon2 password-based key derivation function, as described in IETF RFC 9106. It is memory-hard in the sense that it deliberately requires a significant amount of RAM for efficient computation. The intention of this is to render brute forcing of passwords on systems that lack large amounts of main memory (such as GPUs or ASICs) computationally infeasible.

Argon2d (Argon2i) uses data-dependent (data-independent) memory access and primary seek to address trade-off (side-channel) attacks.

Argon2id is a hybrid construction which, in the first two slices of the first pass, generates reference addresses data-independently as in Argon2i, whereas in later slices and next passes it generates them data-dependently as in Argon2d.

Sbox-hardened version Argon2ds is not supported.

For more information, please refer to RFC 9106.

### Supported parameters
The supported parameters are:

"pass" (OSSL_KDF_PARAM_PASSWORD) <octet string>

"salt" (OSSL_KDF_PARAM_SALT) <octet string>

"secret" (OSSL_KDF_PARAM_SECRET) <octet string>

"iter" (OSSL_KDF_PARAM_ITER) <unsigned integer>

"size" (OSSL_KDF_PARAM_SIZE) <unsigned integer>

"properties" (OSSL_KDF_PARAM_PROPERTIES) <UTF8 string>

These parameters work as described in "PARAMETERS" in EVP_KDF(3). Note that RFC 9106 recommends 128 bits salt for most applications, or 64 bits salt in the case of space constraints. At least 128 bits output length is recommended.

Note that secret (or pepper) is an optional secret data used along the password.

"threads" (OSSL_KDF_PARAM_THREADS) <unsigned integer>

The number of threads, bounded above by the number of lanes. This can only be used with built-in thread support. Threading must be explicitly enabled. See EXAMPLES section for more information.

"ad" (OSSL_KDF_PARAM_ARGON2_AD) <octet string>

Optional associated data, may be used to "tag" a group of keys, or tie them to a particular public key, without having to modify salt.

"lanes" (OSSL_KDF_PARAM_ARGON2_LANES) <unsigned integer>

Argon2 splits the requested memory size into lanes, each of which is designed to be processed in parallel. For example, on a system with p cores, it's recommended to use p lanes. The number of lanes is used to derive the key. It is possible to specify more lanes than the number of available computational threads. This is especially encouraged if multi-threading is disabled.

"memcost" (OSSL_KDF_PARAM_ARGON2_MEMCOST) <unsigned integer>

Memory cost parameter (the number of 1k memory blocks used).

"version" (OSSL_KDF_PARAM_ARGON2_VERSION) <unsigned integer>

Argon2 version. Supported values: 0x10, 0x13 (default).

"early_clean" (OSSL_KDF_PARAM_EARLY_CLEAN) <unsigned integer>

If set (nonzero), password and secret stored in Argon2 context are zeroed early during initial hash computation, as soon as they are not needed. Otherwise, they are zeroed along the rest of Argon2 context data on clear, free, reset. This can be useful if, for example, multiple keys with different ad value are to be generated from a single password and secret.

## EXAMPLES
This example uses Argon2d with password "1234567890", salt "saltsalt", using 2 lanes, 2 threads, and memory cost of 65536:

```
 #include <string.h>                 /* strlen               */
 #include <openssl/core_names.h>     /* OSSL_KDF_*           */
 #include <openssl/params.h>         /* OSSL_PARAM_*         */
 #include <openssl/thread.h>         /* OSSL_set_max_threads */
 #include <openssl/kdf.h>            /* EVP_KDF_*            */
 int main(void)
 {
     int retval = 1;
     EVP_KDF *kdf = NULL;
     EVP_KDF_CTX *kctx = NULL;
     OSSL_PARAM params[6], *p = params;
     /* argon2 params, please refer to RFC9106 for recommended defaults */
     uint32_t lanes = 2, threads = 2, memcost = 65536;
     char pwd[] = "1234567890", salt[] = "saltsalt";
     /* derive result */
     size_t outlen = 128;
     unsigned char result[outlen];
     /* required if threads > 1 */
     if (OSSL_set_max_threads(NULL, threads) != 1)
         goto fail;
     p = params;
     *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_THREADS, &threads);
     *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_LANES,
                                        &lanes);
     *p++ = OSSL_PARAM_construct_uint32(OSSL_KDF_PARAM_ARGON2_MEMCOST,
                                        &memcost);
     *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_SALT,
                                              salt,
                                              strlen((const char *)salt));
     *p++ = OSSL_PARAM_construct_octet_string(OSSL_KDF_PARAM_PASSWORD,
                                              pwd,
                                              strlen((const char *)pwd));
     *p++ = OSSL_PARAM_construct_end();
     if ((kdf = EVP_KDF_fetch(NULL, "ARGON2D", NULL)) == NULL)
         goto fail;
     if ((kctx = EVP_KDF_CTX_new(kdf)) == NULL)
         goto fail;
     if (EVP_KDF_derive(kctx, &result[0], outlen, params) != 1)
         goto fail;
     printf("Output = %s\n", OPENSSL_buf2hexstr(result, outlen));
     retval = 0;
 fail:
     EVP_KDF_free(kdf);
     EVP_KDF_CTX_free(kctx);
     OSSL_set_max_threads(NULL, 0);
     return retval;
 }
```

## NOTES
"ARGON2I", "ARGON2D", and "ARGON2ID" are the names for this implementation; it can be used with the EVP_KDF_fetch() function.

## CONFORMING TO
RFC 9106 Argon2, see <https://www.rfc-editor.org/rfc/rfc9106.txt>.

## SEE ALSO
EVP_KDF(3), EVP_KDF_CTX_new(3), EVP_KDF_CTX_free(3), EVP_KDF_CTX_set_params(3), EVP_KDF_derive(3), "PARAMETERS" in EVP_KDF(3)

## HISTORY
This functionality was added to OpenSSL 3.2.

## COPYRIGHT
Copyright 2022-2024 The OpenSSL Project Authors. All Rights Reserved.

Licensed under the Apache License 2.0 (the "License"). You may not use this file except in compliance with the License. You can obtain a copy in the file LICENSE in the source distribution or at <https://www.openssl.org/source/license.html>.