raddb/sites-available/originate-coa

   1 # -*- text -*-
   2 ######################################################################
   3 #
   4 #  The server can originate Change of Authorization (CoA) or
   5 #  Disconnect request packets.  These packets are used to dynamically
   6 #  change the parameters of a users session (bandwidth, etc.), or
   7 #  to forcibly disconnect the user.
   8 #
   9 #  There are some caveats.  Not all NAS vendors support this
  10 #  functionality.  Even for the ones that do, it may be difficult to
  11 #  find out what needs to go into a CoA-Request or Disconnect-Request
  12 #  packet.  All we can suggest is to read the NAS documentation
  13 #  available from the vendor.  That documentation SHOULD describe
  14 #  what information their equipment needs to see in a CoA packet.
  15 #
  16 #  This information is usually a list of attributes such as:
  17 #
  18 #       NAS-IP-Address (or NAS-IPv6 address)
  19 #       NAS-Identifier
  20 #       User-Name
  21 #       Acct-Session-Id
  22 #
  23 #  CoA packets can be originated when a normal Access-Request or
  24 #  Accounting-Request packet is received.  Simply update the
  25 #  "coa" list:
  26 #
  27 #       update coa {
  28 #              User-Name = "%{User-Name}"
  29 #              Acct-Session-Id = "%{Acct-Session-Id}"
  30 #              NAS-IP-Address = "%{NAS-IP-Address}"
  31 #       }
  32 #
  33 #  And the CoA packet will be sent.  You can also send Disconnect
  34 #  packets by using "update disconnect { ...".
  35 #
  36 #  This "update coa" entry can be placed in any section (authorize,
  37 #  preacct, etc.), EXCEPT for pre-proxy and post-proxy.  The CoA
  38 #  packets CANNOT be sent if the original request has been proxied.
  39 #
  40 #  The CoA functionality works best when the RADIUS server and
  41 #  the NAS receiving CoA packets are on the same network.
  42 #
  43 #  If "update coa { ... " is used, and then later it becomes necessary
  44 #  to not send a CoA request, the following example can suppress the
  45 #  CoA packet:
  46 #
  47 #       update control {
  48 #               Send-CoA-Request = No
  49 #       }
  50 #
  51 #  The default destination of a CoA packet is the NAS (or client)
  52 #  the sent the original Access-Request or Accounting-Request.  See
  53 #  raddb/clients.conf for a "coa_server" configuration that ties
  54 #  a client to a specific home server, or to a home server pool.
  55 #
  56 #  If you need to send the packet to a different destination, update
  57 #  the "coa" list with one of:
  58 #
  59 #       Packet-Dst-IP-Address = ...
  60 #       Packet-Dst-IPv6-Address = ...
  61 #       Home-Server-Pool = ...
  62 #
  63 #  That specifies an Ipv4 or IPv6 address, or a home server pool
  64 #  (such as the "coa" pool example below).  This use is not
  65 #  recommended, however,  It is much better to point the client
  66 #  configuration directly at the CoA server/pool, as outlined
  67 #  earlier.
  68 #
  69 #  If the CoA port is non-standard, you can also set:
  70 #
  71 #       Packet-Dst-Port
  72 #
  73 #  to have the value of the port.
  74 #
  75 ######################################################################
  76
  77 #
  78 #  When CoA packets are sent to a NAS, the NAS is acting as a
  79 #  server (see RFC 5176).  i.e. it has a type (accepts CoA and/or
  80 #  Disconnect packets), an IP address (or IPv6 address), a
  81 #  destination port, and a shared secret.
  82 #
  83 #  This information *cannot* go into a "client" section.  In the future,
  84 #  FreeRADIUS will be able to receive, and to proxy CoA packets.
  85 #  Having the CoA configuration as below means that we can later do
  86 #  load-balancing, fail-over, etc. of CoA servers.  If the CoA
  87 #  configuration went into a "client" section, it would be impossible
  88 #  to do proper proxying of CoA requests.
  89 #
  90 home_server localhost-coa {
  91         type = coa
  92
  93         #
  94         #  Note that a home server of type "coa" MUST be a real NAS,
  95         #  with an ipaddr or ipv6addr.  It CANNOT point to a virtual
  96         #  server.
  97         #
  98         ipaddr = 127.0.0.1
  99         port = 3799
 100
 101         #  This secret SHOULD NOT be the same as the shared
 102         #  secret in a "client" section.
 103         secret = testing1234
 104
 105         #  CoA specific parameters.  See raddb/proxy.conf for details.
 106         coa {
 107                 irt = 2
 108                 mrt = 16
 109                 mrc = 5
 110                 mrd = 30
 111         }
 112 }
 113
 114 #
 115 #  CoA servers can be put into pools, just like normal servers.
 116 #
 117 home_server_pool coa {
 118         type = fail-over
 119
 120         # Point to the CoA server above.
 121         home_server = localhost-coa
 122
 123         #  CoA requests are run through the pre-proxy section.
 124         #  CoA responses are run through the post-proxy section.
 125         virtual_server = originate-coa.example.com
 126
 127         #
 128         #  Home server pools of type "coa" cannot (currently) have
 129         #  a "fallback" configuration.
 130         #
 131 }
 132
 133 #
 134 #  When this virtual server is run, the original request has FINISHED
 135 #  processing.  i.e. the reply has already been sent to the NAS.
 136 #  You can access the attributes in the original packet, reply, and
 137 #  control items, but changing them will have NO EFFECT.
 138 #
 139 #  The CoA packet is in the "proxy-request" attribute list.
 140 #  The CoA reply (if any) is in the "proxy-reply" attribute list.
 141 #
 142 server originate-coa.example.com {
 143   pre-proxy {
 144         update proxy-request {
 145                 NAS-IP-Address = 127.0.0.1
 146         }
 147   }
 148
 149   #
 150   # Handle the responses here.
 151   #
 152   post-proxy {
 153         switch "%{Response-Packet-Type}" {
 154                 case CoA-ACK {
 155                         ok
 156                 }
 157
 158                 case CoA-NAK {
 159                         # the NAS didn't like the CoA request
 160                         ok
 161                 }
 162
 163                 case Disconnect-ACK {
 164                         ok
 165                 }
 166
 167                 case Disconnect-NAK {
 168                         # the NAS didn't like the Disconnect request
 169                         ok
 170                 }
 171
 172                 # Invalid packet type.  This shouldn't happen.
 173                 case {
 174                      fail
 175                 }
 176         }
 177
 178         #
 179         #  These methods are run when there is NO response
 180         #  to the request.
 181         #
 182         Post-Proxy-Type Fail-CoA {
 183                 ok
 184         }
 185
 186         Post-Proxy-Type Fail-Disconnect {
 187                 ok
 188         }
 189   }
 190 }