AF_IUCV(7)

📦 version 2.44.1, in opensuse-leap 16.0

✨ NAME ✨

AF_IUCV(7) — Sockets for z/VM IUCV and HiperSockets communication 💖

🌸 SYNOPSIS 🌸

#include <sys/socket.h>
#include <netiucv/iucv.h>

iucv_stream_socket = socket(AF_IUCV, SOCK_STREAM, 0);
iucv_packet_socket = socket(AF_IUCV, SOCK_SEQPACKET, 0);

💅 DESCRIPTION 💅

Okay so bestie, the AF_IUCV address family gives you an addressing mode for communications between applications running on System z mainframes. This addressing mode can be used for connections through real HiperSockets and through the z/VM Inter-User Communication Vehicle (IUCV). ✨

HiperSockets facilitate connections between applications across LPARs within a System z mainframe. In particular, an application running on an instance of Linux on System z can communicate with:

  • Itself
  • Other applications running on the same Linux instance
  • An application on an instance of Linux on System z in another LPAR

IUCV facilitates connections between applications across z/VM guest virtual machines within a z/VM system. In particular, an application running on Linux on z/VM can communicate with:

  • Itself
  • Other applications running on the same Linux instance
  • Applications running on other instances of Linux on z/VM within the same z/VM system
  • Applications running on a z/VM guest other than Linux within the same z/VM system
  • The z/VM control program (CP)

The AF_IUCV address family supports stream-oriented sockets (SOCK_STREAM) and connection-oriented datagram sockets (SOCK_SEQPACKET). Stream-oriented sockets can fragment data over several packets. Sockets of type SOCK_SEQPACKET always map a particular socket write or read operation to a single packet. Periodt. 💅

🦋 Features 🦋

For all instances of Linux on System z, the AF_IUCV address family provides:

  • Multiple outgoing socket connections for real HiperSockets in layer3 mode
  • Multiple incoming socket connections for real HiperSockets in layer3 mode

For instances of Linux on z/VM, the AF_IUCV address family also provides:

  • Multiple outgoing socket connections for IUCV
  • Multiple incoming socket connections for IUCV
  • Socket communication with applications utilizing CMS AF_IUCV support

🎀 ADDRESS FORMAT 🎀

An AF_IUCV socket is represented by the following format:

#define AF_IUCV    32

struct sockaddr_iucv {
    sa_family_t    siucv_family;     /* AF_IUCV */
    unsigned short siucv_port;       /* reserved */
    unsigned int   siucv_addr;       /* reserved */
    char           siucv_nodeid[8];  /* reserved */
    char           siucv_user_id[8]; /* user id */
    char           siucv_name[8];    /* application name */
};
  • siucv_family — is set to AF_IUCV (= 32)
  • siucv_port, siucv_addr, siucv_nodeid — are reserved for future use. The siucv_port and siucv_addr fields must be zero. The siucv_nodeid field must be set to exactly eight blanks.
  • siucv_user_id — specifies a HiperSockets device or a z/VM guest virtual machine. This specification implicitly sets the connection type for the socket to a HiperSockets connection or to a z/VM IUCV connection.

This field must be eight characters long and, if necessary, padded with blanks on the right.

For HiperSockets connections, the siucv_user_id field specifies the identifier that is set with the hsuid sysfs attribute of the HiperSockets device. For bind(2) this is the identifier of a local device, and for connect(2) this is the identifier of the HiperSockets device of the communication peer.

For IUCV connections, the siucv_user_id field specifies a z/VM user ID. For bind(2) this is the identifier of the local z/VM guest virtual machine, and for connect(2) this is the identifier of the z/VM guest virtual machine for the communication peer.

💡 Tip: For bind(2) you can also specify eight blanks. The AF_IUCV address family support then automatically substitutes the local z/VM user ID for you. Slay.
  • siucv_name — is set to the application name by which the socket is known. Servers advertise application names and clients use these application names to connect to servers. This field must be eight characters long, and if necessary, padded with blanks on the right.

Similar to TCP or UDP ports, application names distinguish distinct applications on the same operating system instance. Do not call bind(2) for names beginning with lnxhvc. These names are reserved for the z/VM IUCV HVC device driver (see also hvc_iucv(9)). Ngl, respect the reserved names. 🙈

🔥 SOCKET OPTIONS 🔥

Socket options can be set with setsockopt(2) and read with getsockopt(2) by specifying SOL_IUCV as the socket level.

  • SO_IPRMDATA_MSG — Enables the application to send up to seven bytes of socket data in the parameter list of an IUCV message. Use this option for IUCV connections to increase performance when transferring small amounts of data. For HiperSockets connections, this option has no effect.

To send data in the parameter list, specify a non-zero integer value.

⚠️ Note: Use this option with care, older AF_IUCV versions do not support receiving socket data in the parameter list and shut down the socket on which a parameter list message has been received.
  • SO_MSGLIMIT — Modifies the message limit for communication paths. The message limit specifies the maximum number of outstanding messages that are allowed for established connections. For IUCV connections this setting can be lowered by z/VM when a connection is established.

The message limit is an integer value in range 1 to 65535. The default value is 65535 for IUCV connections and 128 for HiperSockets connections.

The message limit must be set before connect(2) or listen(2) is called for sockets. For sockets that are already connected or listening for connections, the message limit cannot be changed. New sockets created by accept(2) inherit the message limit that has been set for the listening socket.

getsockopt(2) returns the default message limit or the limit that has been set. For connected sockets, the current message limit is returned. For IUCV connections, there are two parameters that specify the message limit: getsockopt(2) and the z/VM IUCV MSGLIMIT parameter. If the two parameters specify different values for the message limit, the lower value is used.

See the "SETUP FOR IUCV CONNECTIONS" section for setting IUCV MSGLIMIT authorizations.

  • SO_MSGSIZE — getsockopt(2) returns the maximum message size a bound AF_IUCV socket can handle. The maximum message size for connections through HiperSockets depends on the MTU size of the underlying HiperSockets connection. For sockets that are not yet bound the maximum message size cannot be determined.

💖 ANCILLARY DATA 💖

Ancillary data is sent and received using sendmsg(2) and recvmsg(2). To send ancillary data, set the cmsg_level field of struct cmsghdr to SOL_IUCV and the cmsg_type field to a type of ancillary data that is supported by the AF_IUCV address family. For more information see cmsg(3). 🫶

Currently, the only supported type is:

💌 SCM_IUCV_TRGCLS

Send or receive IUCV target class information. The IUCV target class can be used to classify and identify an IUCV message at the IUCV protocol level. If the target class is not specified as ancillary data, it is set to zero.

The target class is a number of type uint32_t.

🌈 SETUP FOR HIPERSOCKETS CONNECTIONS 🌈

This section applies to HiperSockets connections and explains the configuration of a HiperSockets device used for AF_IUCV address family support. Bestie, this is the setup part — stay with me. 💜

To run an AF_IUCV socket application using HiperSockets connections, the socket must be bound to a particular HiperSockets device configured with layer3 mode. Use the hsuid attribute of a HiperSockets device to identify it to the AF_IUCV address family support.

The identifier must adhere to these rules:

  • It must be 1 to 8 characters.
  • It must be unique across your environment.
  • It must not match any z/VM user ID in your environment.

To set an identifier, issue a command like this:

echo identifier > /sys/devices/qeth/<bus-ID>/hsuid

You can then address this device by specifying the hsuid as the value for the siucv_user_id field in the sockaddr_iucv addressing structure.

For example, to use "MYHOST01" to bind AF_IUCV sockets to the HiperSockets device with bus-ID 0.0.8000, run:

echo "MYHOST01" > /sys/devices/qeth/0.0.8000/hsuid

🛠️ SETUP FOR IUCV CONNECTIONS

Okay so this whole section is for z/VM IUCV connections specifically — it's your cheat sheet for the IUCV statements you need on your z/VM guest virtual machines. 💅 If you want the deep lore, plus the general IUCV setup info for z/VM guest virtual machines, go read z/VM CP Programming Services and z/VM CP Planning and Administration.

🔑 Granting IUCV authorizations

Use the IUCV directory control statement to hand out the authorizations you need. Slay.

  • IUCV ALLOW — this one lets any other z/VM guest virtual machine set up a communication path with this z/VM guest virtual machine. And with this statement in place, the z/VM guest virtual machine that kicks off the communication needs no further authorization. Zero extra paperwork, iconic.
  • IUCV ANY — this one lets this z/VM guest virtual machine set up a communication path with any other z/VM guest virtual machine. Main character energy, free to roam. 🦋
  • IUCV user_ID — this one lets this z/VM guest virtual machine set up a communication path to the z/VM guest virtual machine whose z/VM user ID is user_ID. Very "I only text my one bestie" of it.

You can specify multiple IUCV statements, no cap. And on any of these IUCV statements you can tack on the MSGLIMIT limit parameter. limit sets the max number of outstanding messages allowed for each connection that this statement authorizes. If you don't give a value for MSGLIMIT, it uses the maximum, 65535. 🙈

📏 Setting a connection limit

Use the OPTION statement to cap how many concurrent connections you'll tolerate. Boundaries! We love them.

  • OPTION MAXCONN maxno — maxno is the maximum number of IUCV connections allowed for this virtual machine. Default is 64. The maximum is 65535. ✨

🍓 Example

These sample statements let any z/VM guest virtual machine connect to your z/VM guest virtual machine with a max of 10000 outstanding messages for each incoming connection. Your z/VM guest virtual machine is allowed to connect to all other z/VM guest virtual machines. And the total number of connections for your z/VM guest virtual machine can't go over 100. Literally the whole vibe in three lines:

IUCV ALLOW MSGLIMIT 10000
IUCV ANY
OPTION MAXCONN 100

💀 ERRORS

Several socket operations hand back error conditions that mean something special in AF_IUCV land. Those error conditions and their descriptions are all listed below. 👇

If you want the complete list of errors for a given socket operation, check that operation's manual page.

  • ECONNREFUSED — connect(2) was called, but the target system isn't listening on the application name. Not me getting left on read by a socket. 😭
  • ENETUNREACH — connect(2) was called, but the target z/VM guest virtual machine isn't logged on. So make sure the z/VM guest virtual machine your app wants to connect to is actually logged on. Please. 🫶
  • EAGAIN — a few flavors of "too much going on" here:
    • connect(2) was called, but the maximum number of IUCV connections was exceeded for the calling or for the target z/VM guest virtual machine. This error can be temporary, so your application might try again after some time. If it keeps happening, increase the maximum number of connections (for one or both z/VM guest virtual machines). Peep the "SETUP FOR IUCV CONNECTIONS" section about the required authorization statement. 🔥
    • sendmsg(2) was called, but the maximum number of outstanding messages for the socket connection has been reached — for example, if there's data available that the communication peer hasn't received yet.
    • If you need to, raise the message limit with the setsockopt(2) function for HiperSockets and IUCV connections. And also raise the IUCV message limit as explained in the "Granting IUCV authorizations" section. ⭐
  • EACCES — connect(2) was called, but the calling z/VM guest virtual machine is missing IUCV authorization. See the "SETUP FOR IUCV CONNECTIONS" section about the required IUCV authorizations. No authorization, no entry. 🚫
  • ENODEV — connect(2) or sendmsg(2) was called, but the HiperSockets device bound to the AF_IUCV socket doesn't exist. 💀
  • ENETDOWN — connect(2) or sendmsg(2) was called, but the HiperSockets device bound to the AF_IUCV socket isn't activated.
  • EBADFD — honestly a whole cluster of "the socket is not in the state you think it's in":
    • connect(2) was called, but for HiperSockets connections the AF_IUCV socket isn't bound — or, for IUCV connections, the socket is in neither open nor bound state.
    • bind(2) was called, but the AF_IUCV socket is no longer in open state.
    • accept(2) was called, but the AF_IUCV socket isn't listening.
    • getsockopt(2) was called, but the AF_IUCV socket isn't bound.
  • EINVAL — the classic "that's not valid" moment:
    • connect(2) or bind(2) was called, but the siucv_family field of the specified sockaddr_iucv structure isn't set to AF_IUCV.
    • listen(2) was called, but the AF_IUCV socket hasn't been bound to an address yet. Always call bind(2) before listen(2). Order matters, bestie. 🌸
    • setsockopt(2) was called with option SO_MSGLIMIT for sockets that are already connected.
  • ENOPROTOOPT — setsockopt(2) or getsockopt(2) was called, but the socket level wasn't set to SOL_IUCV, or the specified socket option isn't supported. 🙈
  • EOPNOTSUPP — nope, that's not supported, twice over:
    • sendmsg(2) or recvmsg(2) might have been called with the MSG_OOB flag set. AF_IUCV does not support sending or receiving out-of-band data on its sockets.
    • For SOCK_SEQPACKET sockets, sendmsg(2) was called without the MSG_EOR flag set. AF_IUCV doesn't support segmentation, so the "end-of-record" (MSG_EOR) flag must always be set. Non-negotiable, periodt. 👑
  • EPROTONOSUPPORT — socket(2) was called with a protocol that isn't supported. The socket protocol parameter must be either zero or PF_IUCV. That's the whole menu. 🎀
  • EAFNOSUPPORT — socket(2) was called with AF_IUCV, but the AF_IUCV address family isn't supported by the current Linux kernel. Make sure your Linux kernel was compiled with support for the latest version of the AF_IUCV address family. 💜
  • EADDRINUSE — bind(2) was called with an siucv_name that's already used for another AF_IUCV socket. Name's taken, babe. ✨

Other errors can be generated by the generic socket layer — see the respective manual pages for more info.

👀 SEE ALSO

connect(2), recvmsg(2), sendmsg(2), socket(2), setsockopt(2), getsockopt(2), cmsg(3), socket(7)

And the reading list, fr fr:

  • Linux on System z - Device Drivers, Features, and Commands
  • z/VM CP Planning and Administration
  • z/VM CP Programming Services

🌈 HISTORY

AF_IUCV, version 1.0 🎀

  • Initial version.

AF_IUCV, version 1.1 🦋

  • Support for sending socket data in the parameter list of an IUCV message (SO_IPRMDATA_MSG).
  • Access the target class of an IUCV message as ancillary data using sendmsg(2) and recvmsg(2).
  • Support for SOCK_SEQPACKET sockets to facilitate development of native IUCV applications that interact with AF_IUCV.

AF_IUCV, version 1.2 🔥

  • Support for HiperSockets connections.

That's the whole page, bestie — drop of s390-tools, dated August 2011, filed under AF_IUCV(7). Go forth and connect responsibly 💖✨

📦 where this page comes from