Documentation/networking/xfrm/xfrm_migrate_state.rst

Source file repositories/reference/linux-study-clean/Documentation/networking/xfrm/xfrm_migrate_state.rst

File Facts

System
Linux kernel
Corpus path
Documentation/networking/xfrm/xfrm_migrate_state.rst
Extension
.rst
Size
11132 bytes
Lines
275
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

struct xfrm_user_migrate_state {
        struct xfrm_usersa_id  id;       /* spi, daddr, proto, family */
        xfrm_address_t         new_daddr;
        xfrm_address_t         new_saddr;
        struct xfrm_mark       old_mark; /* SA lookup: key = v & m */
        struct xfrm_selector   new_sel;  /* new selector (see Flags) */
        __u32                  new_reqid;
        __u32                  flags;    /* XFRM_MIGRATE_STATE_* */
        __u16                  new_family;
        __u16                  reserved;  /* must be zero */
    };

The ``reserved`` field must be set to zero; the kernel rejects any
other value with ``-EINVAL``.

Supported Attributes
====================

The following fields in ``xfrm_user_migrate_state`` are always explicit
and are not inherited from the existing SA. Passing zero is not equivalent
to "keep unchanged" — zero is used as-is:

- ``new_daddr`` - new destination address
- ``new_saddr`` - new source address
- ``new_family`` - new address family
- ``new_reqid`` - new reqid (0 = no reqid)
- ``new_sel`` - new selector; used when ``XFRM_MIGRATE_STATE_UPDATE_H2H_SEL`` is
  not set (see `Flags`_ below)
- ``flags`` - bitmask of ``XFRM_MIGRATE_STATE_*`` flags (see `Flags`_ below)

The following netlink attributes are also accepted. Omitting an attribute
inherits the value from the existing SA (omit-to-inherit).

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Attribute
     - Description
   * - ``XFRMA_MARK``
     - Mark on the migrated SA (``struct xfrm_mark``). Absent inherits
       ``old_mark``. To use no mark on the new SA, send ``XFRMA_MARK``
       with ``{0, 0}``.
   * - ``XFRMA_ENCAP``
     - UDP encapsulation template; only ``UDP_ENCAP_ESPINUDP`` is supported.
       Set ``encap_type=0`` to remove encap.
   * - ``XFRMA_OFFLOAD_DEV``
     - Hardware offload configuration (``struct xfrm_user_offload``). Absent
       copies offload from the existing SA. When
       ``XFRM_MIGRATE_STATE_CLEAR_OFFLOAD`` is set in ``flags``, the new SA has
       no offload; this flag is mutually exclusive with ``XFRMA_OFFLOAD_DEV``
       and sending both returns ``-EINVAL``.
   * - ``XFRMA_SET_MARK``
     - Output mark on the migrated SA; pair with ``XFRMA_SET_MARK_MASK``.
       Send 0 to clear.
   * - ``XFRMA_NAT_KEEPALIVE_INTERVAL``
     - NAT keepalive interval in seconds. Requires encap. Send 0 to clear.
       Automatically cleared when encap is removed; setting a non-zero
       value without encap returns ``-EINVAL``.
   * - ``XFRMA_MTIMER_THRESH``
     - Mapping maxage threshold. Only valid on input SAs; setting on an
       output SA returns ``-EINVAL``. Requires encap. Send 0 to clear.
       Automatically cleared when encap is removed; setting a non-zero
       value without encap returns ``-EINVAL``.

The following SA properties are immutable and cannot be changed via
``XFRM_MSG_MIGRATE_STATE``: algorithms (``XFRMA_ALG_*``), replay state,
direction (``XFRMA_SA_DIR``), and security context (``XFRMA_SEC_CTX``).

Flags

Annotation

Implementation Notes