mdiioctl(7)


mdiioctl -- MDI ioctl commands

Synopsis

Description

The SCO MDI ioctls are used with the streamio7.ISTR STREAM ioctl that is documented on the streamio(7) manual page.

MDI ioctls are used to change the operation of and get information about the network adapter being driven by the MDI driver. They are sent by the MAC user in STREAMS messages of type M_IOCTL(D7str), with any associated data passed in a M_DATA(D7str) message type.

Address control

These ioctl commands are used to get and control MDI addresses; see ``MDI networking destination addresses''.

MACIOC_GETADDR

Requests that the MDI driver return the current MAC address.

Parameters
The ioctl(2) data contains space into which the MDI driver should copy its MAC address.

Data returned
The MDI driver should fill the ioctl data area with its MAC address. This address is the current in-use MAC address. The data is one of the following:

M_IOCACK(D7str)
Acknowledge successful completion of the operation. Set ioc_rval set to zero and ioc_count set to the size of the MAC address in the associated M_DATA(D7str) block, with control information passed in an iocblk(D4str) structure.

M_IOCNAK(D7str)
Acknowledge unsuccessful completion of the operation. Set ioc_count to zero, ioc_rval to -1, and ioc_error set to EINVAL if the device does not use MAC addresses. For other error conditions, set ioc_error to an appropriate value from errnos(D5).

MACIOC_PROMISC

Requests that the MDI driver enable promiscuous mode on the adapter. Enabling promiscuous mode means: Promiscuous mode is disabled when the MDI device is opened, and is reset when the device is closed; see open(D2mdi) and close(D2mdi). Multiple opens of the same MDI device are not permitted; this means that only one MDI consumer (for example, a user application or kernel driver) at a time can access the the device. Normally, the dlpid(1M) daemon opens the MDI device when the system goes into multiuser mode.

Promiscuous mode support is optional for MDI drivers. Set the PROMISCUOUS parameter in the driver's bcfg(4dsp) file(s) to true if the driver implements promiscuous mode, or to false if it does not. Use the ndcfg(1M) utility in interactive mode with the promiscuous command to determine if installed network devices support promiscuous mode.

This ioctl can only be sent directly to the MDI device; it will not be passed from /dev/netX to /dev/mdi.

The MACIOC_PROMISC ioctl is valid only if the issuing process is root or has equivalent credentials.

Parameters
None. No ioctl data mblk is associated with this ioctl.

Data returned
None.


NOTE: Promiscuous mode can be useful for network troubleshooting; network monitors and other tools rely on promiscuous mode. However, its use can pose significant security risks, particularly when root integrity has been compromised. For this reason, modifications to MDI drivers concerning promiscuous mode are not supported. For more information, see CERT (Computer Emergency Response Team) Coordination Center advisories concerning network monitoring attacks, available at:

http://www.cert.org


MACIOC_GETRADDR

Requests that the MDI driver retrieve the factory MAC address from the controller. This will appear as an M_IOCTL(D7str) message with an associated M_DATA(D7str) block.

Drivers for MDI devices that do not use MAC addresses must use this primitive so that upper-layer calls will fail gracefully.

Parameters
The ioctl data contains space into which the MDI driver should copy its MAC address.

Data returned
The MDI driver should fill the ioctl data area with its MAC address. This address is the current in-use MAC address. The data is one of the following:

M_IOCACK(D7str)
Acknowledge successful completion of the operation. Set ioc_rval set to zero and ioc_count set to the size of the MAC address in the associated M_DATA(D7str) block.

M_IOCNAK(D7str)
Acknowledge unsuccessful completion of the operation. Set ioc_count to zero, ioc_rval to -1, and ioc_error set to EINVAL if the device does not use MAC addresses. For other error conditions, set ioc_error to an appropriate value from errnos(D5).

MACIOC_SETADDR

Requests that the MDI driver set the MAC address in use on the controller. The request will appear as an M_IOCTL(D7str) message block with an associated M_DATA(D7str) block that contains the MAC address to be used. This new address should be used as the source MAC address for all transmitted packets and the controller should be set to receive packets sent to this address, as well as all defined multicast addresses and all MAC level broadcasts. This request should only be acted upon if ioc_uid is set to zero.

The new MAC address must be preserved across a close and subsequent open of the driver. When this driver isunloaded from the kernel and subsequently reloaded, the value of the current MAC address must be reset to the factory MAC address.

Parameters
The ioctl data contains space into which the MDI driver should copy its MAC address.

Data returned
Acknowledgement should be one of the following:

M_IOCACK(D7str)
Set ioc_rval and ioc_count to zero.

M_IOCNAK(D7str)
Set ioc_count to zero, ioc_rval to -1, and ioc_error to one of the following:

EPERM
ioc_uid is non-zero

EINVAL
Device does not use MAC addresses

EACCES
Device does not support changing the MAC address.

For any other error conditions, set ioc_error to an appropriate value from errnos(D5).

Frame control

These ioctl commands control the address to which frames are sent.

MACIOC_SETMCA

Requests that the MDI driver begin receiving frames sent to the requested MAC address in addition to the default address, broadcast address and existing multicast addresses. The driver will continue to receive frames on this MAC address until either a MACIOC_DELMCA ioctl request for this MAC address is received or the MDI device is closed.

Parameters
The ioctl Data contains the MAC address to be added to the MDI driver's multicast address table.

Data returned
The MDI driver should fail the ioctl if the MAC address is not a legal multicast address for that media type. If the MAC address is already in the table, the MDI driver must return success, but should not add a duplicate of the address to the multicast address table.

MACIOC_SETALLMCA

Requests that the MDI driver begin deliverying frames sent to all multicast MAC addresses in addition to the adapter's MAC address, the broadcast address, and existing multicast addresses. The driver will continue to receive frames on all multicast MAC addresses until either a MACIOC_DELALLMCA ioctl request is received or the MDI device is closed.

Parameters
None.

Data returned
The MDI driver should fail this ioctl if the adapter is not capable of receiving all multicast addresses. Do not set promiscuous mode and filter out unicast addresses to support this ioctl.

Acknowledgement should be one of the following:

M_IOCACK(D7str)
Set ioc_rval and ioc_count to zero.

M_IOCNAK(D7str)
Set ioc_count to zero, ioc_rval to -1, and ioc_error to one of the following:

EPERM
ioc_uid is non-zero

EINVAL
Device does not use MAC addresses

MACIOC_DELMCA

Requests that the MDI driver stops receiving frames sent to a MAC address.

Parameters
The ioctl data contains the MAC address to be deleted from the MDI driver's multicast address table.

Data returned
The MDI driver should fail this ioctl if the MAC address to be deleted is not in the multicast address table.

MACIOC_DELALLMCA

Requests that the MDI driver stop receiving frames sent to multicast MAC addresses that have not explicitly been set with MACIOC_ALLMCA.

Parameters
None.

Data returned
Acknowledgement should be one of the following:

M_IOCACK(D7str)
Set ioc_rval and ioc_count to zero.

M_IOCNAK(D7str)
Set ioc_count to zero, ioc_rval to -1, and ioc_error to one of the following:

EPERM
ioc_uid is non-zero

EINVAL
Device does not use MAC addresses

Statistics

MDI includes a statistics mechanism that uses media-specific statistics structures:

mac_stats_eth(D4mdi)
Ethernet

mac_stats_tr(D4mdi)
IEEE 802.5 token passing ring

mac_stats_fddi(D4mdi)
ANSI Fiber Distributed Data Interface (FDDI)

mac_stats_isdn(D4mdi)
ISDN (Integrated Services Digital Network)

This replaces the mechanism based on the ifstats(D4) structure to provide information to the netstat(1Mtcp) command.

MACIOC_GETSTAT

Requests that the MDI driver return media-specific statistics containing information about the MDI driver, the network adapter and the network itself.

Parameters
The ioctl data contains space into which the MDI driver should copy its statistics structure.

Data returned
The MDI driver should fill the ioctl data area with the its statistics structure.

MACIOC_SETSTAT

Requests that the MDI driver modify the MIB settable attibutes related to the MDI driver, the network adapter and the network itself.

MACIOC_CLRSTAT

Requests that the MDI driver clear all the information collected in its statistics structure.

Parameters
None. No ioctl data mblk is associated with this ioctl.

Data returned
None.

Differences between versions

The SCO OpenServer MDI supports the following primitives that are not supported by MDI version 2: MACIOC_GETMCSIZ, MACIOC_GETMCA, as well as the MDI_NMCADDR macro.

Files

/dev/mdi/*

References

isdn(7)

Section D2mdi manual pages, Section D3mdi manual pages, Section D4mdi manual pages, Section D7mdi manual pages,

Developing MDI network adapter drivers

``MDI ioctls''

Developing STREAMS modules and drivers.


30 January 1998
© 1998 The Santa Cruz Operation, Inc. All rights reserved.