*** xref:xlat/alternation.adoc[Alternation Syntax]
*** xref:xlat/conversion.adoc[Data Conversion]
*** xref:xlat/deprecated.adoc[Deprecated Functions]
-*** xref:xlat/file.adoc[File Handling]
+*** xref:xlat/file/index.adoc[File Handling]
+**** xref:reference:xlat/file/escape.adoc[escape]
+**** xref:xlat/file/exists.adoc[exists]
+**** xref:xlat/file/head.adoc[head]
+**** xref:xlat/file/rm.adoc[rm]
+**** xref:xlat/file/size.adoc[size]
+**** xref:xlat/file/tail.adoc[tail]
*** xref:xlat/function.adoc[Function Syntax]
*** xref:xlat/hash.adoc[Hashing]
*** xref:xlat/interpreter.adoc[Interpreter State and Debugging]
+++ /dev/null
-= File Handling functions
-
-The file handling functions allow for a limited number of operations on files.
-
-The filenames can be taken from `tainted` sources, in which cases special characters such as '`/`' and '`$`' are escaped. Any special character is replaced with an underscore, followed by the hex value of the character. Valid UTF-8 characters are allowed.
-
-For example, the `tainted` string `user@freeradius.org/..` will turn into the filename `user@freeradius.org_2f..`. This operation renders the filename "safe" for operations on the local file system. It is not possible for `tainted` data to create files, or to perform directory traversal attacks.
-
-== %file.escape(_string_)
-
-.Return: _string_
-
-This function returns an escaped or "safe" version of the input string.
-
-In some cases, as when using `%exec(...)`, it is impossible to determine which arguments are filenames, and which are simple strings. This function allows the server to safely pass in a filename to external programs.
-
-The returned filename is guaranteed to be safe to use. Any portion of the filename which is taken from a "safe" source (i.e. configuration files, etc. controlled by an administrator) is used as-is. Any portion of the filename which is taken from an "unsafe" source (i.e. network apckets) is escaped. The result is that characters like `/` in unsafe inputs cannot be used to perform directory traversal attacks.
-
-.Safely pass a filename to `%exec(...)`
-====
-[source,unlang]
-----
-filename = "${logdir}/" + %file.escape(%{User-Name})
-
-%exec("/bin/rm", %{filename})
-----
-====
-
-
-== %file.exists(_string_)
-
-.Return: _bool_
-
-This function returns `true` if a file exists, or `false` if the file does not exist.
-
-.Checking if a file exists
-====
-[source,unlang]
-----
-if %file.exists("/var/log/radius.log") {
- # do things...
-}
-----
-====
-
-== %file.head(_string_)
-
-.Return: _string_
-
-This function returns the first line of the file. If the file does not exist, or if the line is more than 256 characters in length, it fails and nothing is returned.
-
-.Returning the first line of a file
-====
-[source,unlang]
-----
-string line
-
-line := %file.head("/var/log/radius.log")
-----
-====
-
-== %file.rm(_string_)
-
-.Return: _bool_
-
-This function removes a file. If the file exists and could be removed, it returns `true`. Otherwise if the file does not exist, or if the file could not be removed, it returns `false.
-
-.Removing a file
-====
-[source,unlang]
-----
-if (%file.size("/var/log/radius.log") > (((uint64)1) << 20)) {
- %file.rm("/var/log/radius.log")
-}
-----
-====
-
-== %file.size(_string_)
-
-.Return: _uint64_
-
-This function checks the size of a file.
-
-.Checking the size of a file
-====
-[source,unlang]
-----
-if (%file.size("/var/log/radius.log") > (((uint64)1) << 20)) {
- %log.info("The log file is getting large!")
-}
-----
-====
-
-== %file.tail(_string_, [ _uint32_ ])
-
-.Return: _string_
-
-This function returns the last line of the file. If the file does not exist, or if the line is more than 256 characters in length, it fails and nothing is returned.
-
-The function takes an optional second argument, which is the number of lines which should be returned. The maximum number of lines which will be returned is limited to 15.
-
-.Returning the first line of a file
-====
-[source,unlang]
-----
-string line
-
-line := %file.tail("/var/log/radius.log")
-
-line := %file.tail("/var/log/radius.log", 2)
-----
-====
-
-// Copyright (C) 2023 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
-// This documentation was developed by Network RADIUS SAS.
--- /dev/null
+= Escape
+
+The `escape` function returns an escaped or "safe" version of the input string.
+
+In some cases, as when using `%exec(...)`, it is impossible to determine which arguments are filenames, and which are simple strings. This function allows the server to safely pass in a filename to external programs.
+
+The returned filename is guaranteed to be safe to use as a filename. Any portion of the filename which is taken from a "safe" source (i.e. configuration files, etc. controlled by an administrator) is used as-is. Any portion of the filename which is taken from an "unsafe" source (i.e. network packts) is escaped. The result is that characters like `/` or `.` in unsafe inputs cannot be used to perform directory traversal attacks.
+
+[#syntax]
+== Syntax
+
+`%file.escape(_string_)`
+
+.Return: _string_
+
+.Safely pass a filename to `%exec(...)`
+====
+[source,unlang]
+----
+filename = "${logdir}/" + %file.escape(User-Name)
+
+%exec("/bin/rm", filename)
+----
+====
--- /dev/null
+= Exists
+
+The `exists` function is used to check if a file exists on the filesystem. This function returns `true` if a file exists, or `false` if the file does not exist.
+
+[#syntax]
+== Syntax
+
+`%file.exists(_string_)`
+
+.Return: _bool_
+
+.Checking if a file exists
+====
+[source,unlang]
+----
+if %file.exists("/var/log/radius.log") {
+ # do things...
+}
+----
+====
--- /dev/null
+= Head
+
+The `head` function returns the first line of the file. If the file does not exist, or if the line is more than 256 characters in length, it fails and nothing is returned.
+
+[#syntax]
+== Syntax
+
+`%file.head(_string_)`
+
+.Return: _string_
+
+.Returning the first line of a file
+====
+[source,unlang]
+----
+string line
+
+line := %file.head("/var/log/radius.log")
+----
+====
--- /dev/null
+= File Handling Functions
+
+The file handling functions perform operations on files.
+
+The filenames can be taken from untrusted sources, in which cases special characters such as '`/`' and '`$`' are escaped. Any special character is replaced with an underscore, followed by the hex value of the character. Valid UTF-8 characters are allowed.
+
+For example, the "unsafe" string `user@freeradius.org/..` will turn into the filename `user@freeradius.org_2f..`. This operation renders the filename "safe" for operations on the local file system. It is not possible for unsafe data to create unexpected files, or to perform directory traversal attacks.
+
+.File Handling Functions
+[options="headers, autowidth]
+|===
+| *Function* | *Description*
+| xref:reference:xlat/file/escape.adoc[escape] | Returns an escaped or safe version of the input string.
+| xref:xlat/file/exists.adoc[exists] | Checks to see if a file exists on the filesystem.
+| xref:xlat/file/head.adoc[head] | Returns the first line of the file.
+| xref:xlat/file/rm.adoc[rm] | Removes a file from the filesystem.
+| xref:xlat/file/size.adoc[size] | Calculates the size of a file.
+| xref:xlat/file/tail.adoc[tail] | Return the last line of a file or the last number(n) of lines of a file.
+|===
+
+// Copyright (C) 2025 Network RADIUS SAS. Licenced under CC-by-NC 4.0.
+// This documentation was developed by Network RADIUS SAS.
--- /dev/null
+= rm
+
+The `rm` function removes a file. If the file exists and could be removed, it returns `true`. Otherwise if the file does not exist, or if the file could not be removed, it returns `false.
+
+[#syntax]
+== Syntax
+
+`%file.rm(_string_)`
+
+.Return: _bool_
+
+.Removing a file
+====
+[source,unlang]
+----
+if (%file.size("/var/log/radius.log") > (((uint64)1) << 20)) {
+ %file.rm("/var/log/radius.log")
+}
+----
+====
--- /dev/null
+= Size
+
+The `size` function is used to calculate the size of a file on the filesystem.
+
+[#syntax]
+== Syntax
+
+`%file.size(_string_)`
+
+.Return: _uint64_
+
+.Checking the size of a file
+====
+[source,unlang]
+----
+if (%file.size("/var/log/radius.log") > (((uint64)1) << 20)) {
+ %log.info("The log file is getting large!")
+}
+----
+====
--- /dev/null
+= Tail
+
+The `tail` function returns the last line of the file. If the file does not exist, or if the line is more than 256 characters in length, it fails and nothing is returned.
+
+The function takes an optional second argument, which is the number of lines which should be returned. The maximum number of lines which will be returned is limited to 15.
+
+[#syntax]
+== Syntax
+
+`%file.tail(_string_, [ _uint32_ ])`
+
+.Return: _string_
+
+.Returning the last line of a file
+====
+[source,unlang]
+----
+string line
+
+line := %file.tail("/var/log/radius.log")
+----
+====
+
+.Returning the last n lines of a file
+====
+[source,unlang]
+----
+string line
+
+line := %file.tail("/var/log/radius.log", 2)
+----
+====
| Keyword | Description
| xref:xlat/attribute.adoc[attributes] | Expand the value of a named attribute.
| xref:xlat/character.adoc[single character] | Single character expansions.
-| xref:xlat/function.adoc[functions] | Function call syntax
+| xref:xlat/function.adoc[functions] | Function call syntax.
| xref:xlat/alternation.adoc[condition] | Conditionally expand a string.
| xref:xlat/builtin.adoc[built-in expansions] | Functions as string length, tolower, etc...
|=====
projects / thirdparty / freeradius-server.git / commitdiff
