1 files changed, 72 insertions, 0 deletions
diff --git a/doc/antora/modules/unlang/pages/list.adoc b/doc/antora/modules/unlang/pages/list.adoc
new file mode 100644
index 0000000..a55a54f
--- /dev/null
+++ b/doc/antora/modules/unlang/pages/list.adoc
@@ -0,0 +1,72 @@
+= Attribute Lists
+
+An attribute list contains a set of attributes.  The allowed lists
+are:
+
+`request`:: Attributes in the incoming request packet.
+
+`reply`:: Attributes in the outgoing reply packet.
+
+`control`:: Attributes in the internal "control" list that is
+associated with the request.
++
+The `control` attributes are used to manage how the request is
+processed.  These attributes are never sent in any packet.
+
+`session-state`:: Attributes which are maintained across multi-packet
+exchanges.
+
+`proxy-request`:: Attributes in the proxied request packet to a home server.
+
+`proxy-reply`:: Attributes in the reply packet from the home server.
+
+`coa`:: Attributes in a CoA-Request packet which is sent to a home server.
+
+`disconnect`:: Attributes in a Disconnect-Request packet which is sent to a home server.
+
+There must be a colon `:` after the list name and before the attribute name.
+This syntax helps the server to distinguish between list names and attribute
+names.
+
+With the exception of `session-state`, all of the above lists are
+ephemeral.  That is, they exist for one packet exchange, and only one
+packet exchange.  When a reply is sent for a request, the above lists
+and all attributes are deleted.  There is no way to reference an
+attribute from a previous packet.  We recommend using a database to
+track complex state.
+
+The `coa` and `disconnect` lists can only be used when the server
+receives an Access-Request or Accounting-Request.  Use `request` and
+`reply` instead of `coa` when the server receives a CoA-Request or
+Disconnect-Request packet.
+
+Adding one or more attributes to either of the `coa` or `disconnect`
+list causes server to originate a CoA-Request or Disconnect-Request
+packet.  That packet is sent when the current Access-Request or
+Accounting-Request has been finished, and a reply sent to the NAS.
+See `raddb/sites-available/originate-coa` for additional information.
+
+In some cases, requests are associated a multi-packet exchange.  For
+those situations, the `session-state` list is automatically saved when
+a reply is sent, and it is automatically restored when the next packet
+in sequence comes in.  Once the packet exchange has been finished, the
+`session-state` list is deleted.
+
+In some cases, there is a parent-child relationship between requests.
+In those situations, it is possible for the policy rules in the child
+to refer to attributes in the parent.  This reference can be made by
+prefixing the _<list>_ name with the `parent` qualifier.  The key word
+`outer` is also a synonym for `parent`.  If there are multiple
+parent-child relationships, the `parent` qualifier can be repeated.
+
+There is, however, no way for the parent to refer to the child.  When
+the child is running, the parent is suspended.  Once the child
+finishes, it is deleted, and is no longer accessible to the parent.
+
+.Examples
+`&parent.request.User-Name` +
+`&parent.reply.Reply-Message` +
+`&parent.parent.session-state.Filter-Id`
+
+// Copyright (C) 2020 Network RADIUS SAS.  Licenced under CC-by-NC 4.0.
+// Development of this documentation was sponsored by Network RADIUS SAS.