Visit Azul.com Support

File Descriptor Policies

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us
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 type file.

  • 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 or inet6 for IPv6 sockets, ipv4 or inet4 for IPv4 sockets, ip or inet for any IPv4/IPv6, unix for Unix domain sockets.

  • localAddress and remoteAddress: * could be used for any bound address.

  • localPort and remotePort: Numeric port, * matches any port.

  • localPath and remotePath: 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 may 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.