File Descriptor Policies
Note
|
File Descriptors are available since zulu17.46 , zulu21.30 (October 2023).
|
CRaC requires that the application closes all open files, network connections etc. On Linux these are represented as file descriptors. However, it might be difficult to alter the application to properly coordinate with the checkpoint, e.g. due to a code in a library you cannot modify. In those cases, CRaC offers a limited handling via configuration.
Note
|
The configuration described here is experimental and work-in-progress functionality, to get feedback from you as a user. Please contact Azul Support ([email protected]) when you discover problems or have ideas for further improvements. |
The configuration is set up by pointing the system property jdk.crac.resource-policies
to a file that consists of several rules separated by three dashes (---
). Lines starting with the hash sign (#
) are ignored. Each rule consists of several key: value
pairs. This is actually a subset of YAML format, so we suggest that you use the .yaml
or .yml
extension for convenient use in an editor.
Note
|
What is described here, only applies to file descriptors opened through the JDK API. Anything opened through native code, cannot be handled this way. |
See an example of this file:
type: file
path: /path/to/my/file
action: close
---
# Here is some comment
type: FILE
path: **/*.log
action: reopen
Each rule has two mandatory properties: type
and action
, with case-insensitive values. Available types are:
-
file
: A file (or directory) on a local filesystem. -
pipe
: An anonymous pipe - named pipes are handled using the typefile
. -
socket
: Network (TCP, UDP, …) or unix socket. -
filedescriptor
: Raw file descriptor that cannot be identified by any of the above.
The order of rules in the file is important; for each file descriptor found open, the first matching rule is applied. Any subsequent rules are ignored.
Files
As the first example shows, files can be selected using the path
property. This supports 'glob' pattern matching. See java.nio.file.FileSystem.getPathMatcher()
JavaDoc for detailed usage.
These are the possible actions:
-
error
: The default action, just print error and fail the checkpoint. -
ignore
: Leave handling of the open file to C/R engine (CRIU). This validates and reopens the file on restore. -
close
: Close the file. An attempt to use it after restore fails with runtime exception. -
reopen
: Close the file, and try to reopen it (on the same position) after restore.
Unless the action is error
, any file found open, triggers a warning to be printed to the logging system. This can be suppressed with the warn: false
property.
Pipes
Anonymous pipes don’t have any means to identify, therefore it makes sense to have at most one rule for these. Available actions are error
, ignore
and close
with the same meaning as for files.
Sockets
The rule can be refined using one of these properties:
-
family
:ipv6
orinet6
for IPv6 sockets,ipv4
orinet4
for IPv4 sockets,ip
orinet
for any IPv4/IPv6,unix
for Unix domain sockets. -
localAddress
andremoteAddress
:*
could be used for any bound address. -
localPort
andremotePort
: Numeric port,*
matches any port. -
localPath
andremotePath
: For Unix sockets, supports 'glob' pattern matching.
Actions error
, ignore
and close
apply as in the previous cases. It is possible to use the action reopen
, too - this closes the socket before checkpoint, but the reopening part is not implemented, therefore, results in a runtime exception after restore. Eventually this will be implemented for listening sockets.
Raw File Descriptors
In some cases you might find that a file descriptor was created without a matching higher-level object (e.g. FileOutputStream
). Such descriptor can be identified either with its numeric value, using value: 123
, or matching its native description: regex: .*something.*
following the java.util.regex.Pattern.compile()
syntax.
For raw descriptors, only the error
, ignore
and close
actions are available.