From: Nick Porter Date: Tue, 10 Jun 2025 07:39:07 +0000 (+0100) Subject: Update mruby sample config with notes on attribute access X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=69f41bde7b3009764ca0d95ece2ca4fb4c058066;p=thirdparty%2Ffreeradius-server.git Update mruby sample config with notes on attribute access --- diff --git a/raddb/mods-available/mruby b/raddb/mods-available/mruby index 7943372d11c..980be95cfb1 100644 --- a/raddb/mods-available/mruby +++ b/raddb/mods-available/mruby @@ -9,17 +9,95 @@ # # The `mruby` module processes attributes through a Ruby interpreter. # -# * Please see the `src/modules/rlm_mruby/example.rb` sample. +# * Please see the `mods-config/mruby/example.rb` sample. # * Please see https://www.ruby-lang.org/en/documentation/ for more # information about the Ruby language. # +# The Ruby method names called when the `mruby` module is called are +# automatically derived from the section in which they are called. +# +# If `mruby` is called in `recv Access-Request`, firstly a method +# `recv_access_request` will be looked for. If that does not exist, then +# a method `recv` will be looked for. +# +# This can be overridden by setting `func_recv_access_request` or `func_recv` +# to point to a different method name. +# +# Each method called during a packet processing section is passed an +# object which represents the packet. +# +# The object contains 4 methods `request`, `reply`, `control` and `session_state` +# which allow access to the pairs in those FreeRADIUS pair lists. +# +# Nested attributes are accessed by using chained methods. Each leaf attribute +# has the following methods +# +# [options="header,autowidth"] +# |=== +# | Method | Purpose | Arguments +# | get(n) | Retrieve the value of an attribute | Optional number specifying the attribute instance. +# | set(v, n) | Set the value of an attribute | Value to set and optional attribute instance. +# | append(v) | Add an instance of an attribute | Value to set on the new instance. +# | del(n) | Delete an attribute | Optional number specifying the attribute instance. +# |=== +# +# Where a specific instance of a nested attribute parent is required, the +# method can be passed an argument to specify the instance number. +# +# For example, if the Ruby method is defined `def self.recv(p)`, then +# attributes in the request can be accessed using syntax of the form: +# +# [options="header,autowidth"] +# |=== +# | Ruby syntax | FreeRADIUS attribute +# | p.request.foo.get | request.foo +# | p.request.baa.baz.get(1) | request.baa.baz[1] +# | p.requestbaa(2).baz.get | request.baa[2].baz +# |=== +# +# Where attribute names contain `-` this should be replaced by `_`, e.g. +# `request.User-Name` becomes `p.request.user_name` +# +# The interface between FreeRADIUS and Ruby is mosty string. +# +# Attributes of type `string` are copied to Ruby as-is. +# They are not escaped or interpreted. +# +# Attributes of type `octets` are copied to Ruby as-is. +# They are not escaped or interpreted. +# +# Numeric attributes are passed as the appropriate Ruby numeric type. +# +# All other attributes are printed, and passed to Ruby as a string value. +# +# IP addresses are sent as strings, e.g. "192.0.2.25", and not as a 4-byte +# binary value. The same applies to other attribute data types. +# +# Attributes can be set by using the `set` method of the leaf attributes E.g. +# +# `p.reply.foo.set('baa')` +# +# The return codes from Ruby methods are passed directly to the server. +# A set of predefined constants are provided to use as return values: +# +# [options="header,autowidth"] +# |=== +# | Ruby constant | FreeRADIUS rcode +# | RLM_MODULE_OK | ok +# | RLM_MODULE_HANDLED | handled +# | RLM_MODULE_INVALID | invalid +# | RLM_MODULE_DISALLOW | disallow +# | RLM_MODULE_NOTFOUND | notfound +# | RLM_MODULE_NOOP | noop +# | RLM_MODULE_UPDATED | updated +# | RLM_MODULE_REJECT | reject +# | RLM_MODULE_FAIL | fail +# |=== +# # # ## Configuration Settings # -# If `mruby` is called for a section which does not have a function defined, -# it will return `noop`. -# mruby { # # filename:: Module to load functions from.