



= Date Module

The `date` module parses dates, and prints them.

The server will normally print dates in its own pre-defined format.
It will also parse dates in a few limited formats.  However, these
operations are for full dates (e.g. January 1, 2020 12:34pm).  The
server does not print dates in other formats, and does not parse
dates in other formats.

The `date` module adds that functionality.  It allows you to print
dates in almost any format you want.  It allows you to parse dates
in almost any format, so long as you know what the fields are, and
how they are defined.



## Configuration Settings


format:: Formatting of the output string.

The format arguments are the same as for the system
`strftime` call.  See `man strftime` for documentation.



utc:: Whether conversions are in UTC or local time.

If `utc` is enabled then any conversions will be made
as UTC, not localtime.

.Default is to use localtime.



### ISO format

The core `xlat`, `%T` returns the request timestamp in `ISO` format
including milliseconds. This expansion returns it without the
millisecond component.

Use e.g. `%date_iso(request):`



### xlat expansions

The `date` module defines an expansion `%date()` When the
expansion is not passed an argument, it returns the current date
printed according to the `format` string defined above.

."Attribute" mode:

If the argument to `%date(...)` is an attribute of `date` or
`integer` type, the date used will be the time given by the
relevant attribute.   If the attributes is of type `string`, the
string will be parsed according to the `format` configuration,
and a Unix date will be returned, as integer seconds since the epoch.

For example, `%date(&Event-Timestamp)` will use the date from the
`link:https://freeradius.org/rfc/rfc2869.html#Event-Timestamp[Event-Timestamp]` attribute as the source of the date for printing.

."Get time" mode:

If the input is the string `request`, the `xlat` will format the
time the current request packet arrived according to the format
string, and return it as a string.

If the input is the string `now`, the `xlat` will behave as
above, for the current time.

If the input string begins with `+`, then the remainder of the
string is interpreted as if the string had been given in the
`format` configuration item.

For example `%date('+%A')` will return `Monday` if today is Monday.

Note that the `%` character is special for xlat expansions, and therefore
either has to be "protected" by string quotation, or the `%` character has
to be escaped itself, as in `%date(+%%A)`

."Integer output"

In some cases, it is useful for the module to parse dates instead
of printing them.  In this mode, the format string is ignored.
Instead, the input arguments are parsed, and the output is an
integer containg the requested value.

The following expansions return integer numbers:

[options="header,autowidth"]
|===
| Parameter       | Description
| %l              | request time in seconds since the epoch.
| %M              | request time microsecond component.
| %c              | current time in seconds since the epoch.
| %C              | current time microsecond component.
| &Attribute-Name | for string attributes, parse the string according to `format`, and return the integer value as a Unix timestamp.
|===


== Default Configuration

```
date {
	format = "%b %e %Y %H:%M:%S %Z"
#	utc = no
}
date date_iso {
	format = "%Y-%m-%dT%H:%M:%SZ"
	utc = yes
}
```
