summaryrefslogtreecommitdiffstats
path: root/raddb/mods-available/json
diff options
context:
space:
mode:
Diffstat (limited to '')
-rw-r--r--raddb/mods-available/json271
1 files changed, 271 insertions, 0 deletions
diff --git a/raddb/mods-available/json b/raddb/mods-available/json
new file mode 100644
index 0000000..02a62ae
--- /dev/null
+++ b/raddb/mods-available/json
@@ -0,0 +1,271 @@
+# -*- text -*-
+#
+#
+# $Id$
+
+#######################################################################
+#
+# = JSON Module
+#
+# The `json` module provides the `json_encode` XLAT, which may be
+# used to encode a given list of attributes into different
+# formats of JSON object.
+#
+
+#
+# ## Configuration Settings
+#
+json {
+
+ #
+ # The only options for the JSON module are to control the output
+ # format of the `json_encode` xlat.
+ #
+ encode {
+
+ #
+ # output_mode:: set the format of JSON documenta
+ # that should be created. This may be one of:
+ #
+ # - object
+ # - object_simple
+ # - array
+ # - array_of_names
+ # - array_of_values
+ #
+ # Examples of each format are given below.
+ #
+# output_mode = object
+
+ #
+ # ### Formatting options for attribute names
+ #
+ attribute {
+ #
+ # prefix:: Add a colon-delimited prefix to all
+ # attribute names in the output document. For example,
+ # with a prefix of "foo", `User-Name` will be output as
+ # `foo:User-Name`.
+ #
+# prefix =
+ }
+
+ #
+ # ### Formatting options for attribute values
+ #
+ value {
+
+ #
+ # single_value_as_array:: always put values in an array
+ #
+ # Output formats will by default put single values as a
+ # JSON object (string, integer, etc). More than one
+ # value will, depending on the output format, be added
+ # as an array.
+ #
+ # When this option is enabled, values will always be
+ # added as an array.
+ #
+# single_value_as_array = no
+
+ #
+ # enum_as_integer:: output the integer value of
+ # enumerated attributes
+ #
+ # Where an attribute has enum values, the textual
+ # representation of the value will normally be output.
+ # Enable this option to force the numeric value
+ # instead.
+ #
+# enum_as_integer = no
+
+ #
+ # always_string:: force all values to be strings
+ #
+ # Integer values are normally written to the JSON
+ # document as numbers (i.e. without quotes). Enable
+ # this option to force all values to be as quoted
+ # strings.
+ #
+# always_string = no
+ }
+
+ }
+
+}
+
+
+#
+# ## Expansions
+#
+# rlm_json provides the below xlat function.
+#
+# ### %{json_encode:...}
+#
+# Generates a JSON document from a given list of attribute templates. The
+# format of document generated can be controlled with the 'encode' section in
+# the module configuration. Attribute values will automatically be escaped so
+# they are JSON-safe.
+#
+# NOTE: The name of the xlat is based on the instance name of this module. If
+# the module was defined as `json jdoc {...}`, then the xlat name will be
+# `jdoc_encode`.
+#
+# The xlat should be passed a list of attributes to encode. Each attribute
+# (after template expansion) will be added to a list of attributes to include
+# in the JSON document. If any of the attributes given are preceeded with a `!`
+# then they are removed from the list. Once all attributes have been processed,
+# the JSON document will be created using this list.
+#
+# For example, the following will produce a JSON document with two attributes in
+# it, `User-Name` and `Calling-Station-Id`, from the RADIUS request:
+#
+# .Example
+#
+# ```
+# %{json_encode:&User-Name &Calling-Station-Id}
+# ```
+#
+# The following will include all attributes in the RADIUS request, except for
+# `User-Password`:
+#
+# .Example
+#
+# ```
+# %{json_encode:&request[*] !&User-Password}
+# ```
+#
+# In another (contrived) example, all the attributes in the RADIUS request will
+# be included in the document, _except_ any attributes in the RADIUS reply.
+# `&User-Name` will be included from the control list, too, if it exists:
+#
+# .Example
+#
+# ```
+# %{json_encode:&request[*] !&reply[*] &control.User-Name}
+# ```
+#
+# #### Output format modes
+#
+# There are a number of output modes, each generating a different format of
+# JSON document.
+#
+# NOTE: In the JSON document, "type" is the type of the _attribute_, which is
+# not necessarily the same as the type of the "value" in the document. See e.g.
+# `Login-Service` above, an enumerated value.
+#
+# The following examples assume the three attributes are being added to the
+# JSON document:
+#
+# ```
+# User-Name = bob
+# Filter-Id = ab
+# Filter-Id += cd
+# ```
+#
+# #### Object output mode examples
+#
+# These modes output a JSON object.
+#
+# .Output mode "object"
+#
+# [source,json]
+# ----
+# {
+# "User-Name": {
+# "type": "string",
+# "value": "bob"
+# },
+# "Filter-Id": {
+# "type": "string",
+# "value": ["ab","cd"]
+# }
+# }
+# ----
+#
+# .Output mode "object_simple"
+#
+# [source,json]
+# ----
+# {
+# "User-Name": "bob",
+# "Filter-Id": ["ab","cd"]
+# }
+# ----
+#
+# #### Array output mode examples
+#
+# The "array" mode is a list of objects, each containing an attribute. If the
+# "single_value_as_array" value option is set then each attribute will only
+# appear once in the array, and "value" will be a list of all the values from
+# the same attribute.
+#
+# .Output mode "array"
+#
+# [source,json]
+# ----
+# [
+# {
+# "name": "User-Name",
+# "type": "string",
+# "value": "bob"
+# },
+# {
+# "name": "Filter-Id",
+# "type": "string",
+# "value": "ab"
+# },
+# {
+# "name": "Filter-Id",
+# "type": "string",
+# "value": "cd"
+# }
+# ]
+# ----
+#
+# .Output mode "array" when "single_value_as_array" is also set
+#
+# [source,json]
+# ----
+# [
+# {
+# "name": "User-Name",
+# "type": "string",
+# "value": ["bob"]
+# },
+# {
+# "name": "Filter-Id",
+# "type": "string",
+# "value": ["ab","cd"]
+# }
+# ]
+# ----
+#
+# The following output modes either do not include the attribute names or
+# values. They are likely to be useful only when the attributes are
+# individually specified and _guaranteed to exist_. In this case the attribute
+# names in `array_of_names` will have corresponding indexes to the values in
+# `array_of_values`.
+#
+# .Output mode "array_of_names"
+#
+# [source,json]
+# ----
+# [
+# "User-Name",
+# "Filter-Id",
+# "Filter-Id"
+# ]
+# ----
+#
+# .Output mode "array_of_values"
+#
+# [source,json]
+# ----
+# [
+# "bob",
+# "ab",
+# "cd"
+# ]
+# ----
+#