Visit Azul.com Support

CRaC Command-Line Options and System Properties

Table of Contents
Need help?
Schedule a consultation with an Azul performance expert.
Contact Us

Command-Line Options

Java command-line options that control the behavior of CRaC.

Command Line Option C/R [1]Use at Checkpoint (C) and/or Restore (R) Zulu Zing

-XX:CRaCCheckpointTo=<value>

Directory path where the checkpoint must be created. The value is required.

To store the checkpoint in an S3-compatible bucket (only available with the Warp CRaC engine), set the <value> to, for example, s3://bucket/some-key. See Using S3 Storage.

C

-XX:CRaCRestoreFrom=<value>

The directory path where the CRaC image is stored which must be used for the restore. It replaces the initializing virtual machine on successful restore. The value is required.

You can optionally pass the name of a new main class and its arguments when using this option. In such a case, the new main method will be invoked with the specified arguments by the thread that initiated the checkpoint, after all CRaC resources have been successfully processed. Check Restoring With New Arguments for more info.

R

-XX:CRaCEngine=<value>

Specify the engine to be used by the CRaC implementation, see CRaC Engines for more details.

  • criu: Engine using Linux CRIU (Checkpoint/Restore In Userspace).

  • warp: Engine which doesn’t require any additional capabilities, neither for checkpoint nor for restore.

  • simengine and pauseengine: Simulation engines used for development purposes only.

C and R

Default on Linux:
criu

Default on macOS and Windows:
simengine

Default:
warp

-XX:CRaCEngineOptions=<value>

A comma-delimited list of key=value to specify the behavior of the selected CRaC engine.

Use the value help, in the exact format -XX:CRaCEngineOptions=help, to get the full list of available options for the selected CRaCEngine. This will let the JVM print the list of supported options and exit.

More info about the available options is documented below for the CRIU and Warp engines.

Example use:

 
java -XX:CRaCEngine=warp \
  -XX:CRaCEngineOptions='compression=true' \
  -XX:CRaCCheckpointTo=./checkpoint \
  -jar app.jar

C and R

null

null

-XX:CRaCMinPid=<value>

The minimal PID value for a process that is restored. See Debugging Coordinated Restore at Checkpoint Failures > Using the CRaCMinPid Option.

The default value is 128 only if the Java process is started with PID 1 (e.g., in a container). For processes started with a different PID, the PID is not adjusted unless this option is set.

R

128

128

-XX:+/-CRaCResetStartTime

Reset JVM’s start time and uptime on restore.

R

true

true

-XX:+/-CRaCIgnoreRestoreIfUnavailable

If the checkpoint image specified for the restore (with -XX:CRaCRestoreFrom) is identified as being unusable, the JVM will continue with the normal startup instead of failing. Enabling this option does not guarantee that the normal startup will follow any failed restore attempt, it only covers an early image/environment verification.

Available in Azul Zulu 25 and October 2025 releases: When restoring with this option, you should specify a main class and its arguments as usual. If the CRaC restore succeeds, these arguments are ignored, but if the restore fails, they are used for the normal startup process. See Transparent Restore or Startup for more info.

R

false

false

-XX:CRaCIgnoredFileDescriptors=<value>

Comma-separated list of file descriptor numbers or paths. All the file descriptors greater than 2 (stdin, stdout and stderr are excluded automatically), that are not in this list, are closed when the VM starts.

R

null

null

-XX:+/-CRaCAllowToSkipCheckpoint

Allow the implementation to not call the Checkpoint if the helper can not be found.

C

false

false

-XX:CRaCAllowedOpenFilePrefixes=<value>

List of path prefixes for files that can be open during the checkpoint. CRaC won’t throw an error upon detecting these and leaves the handling up to the Checkpoint/Restore engine. This option applies only to files opened by native code. For files opened by Java code use -Djdk.crac.resource-policies=…​.

C

/var/lib/sss/mc/ (on Linux)

/var/lib/sss/mc/

-XX:+/-CRaCHeapDumpOnCheckpointException

Dump the heap when a CheckpointException is thrown because of a failing CRaC precondition.

C

false

false

-XX:+/-CRaCPrintResourcesOnCheckpoint

Print the resources used to decide on a CheckpointException. This is a diagnostic feature and must be preceded with -XX:+UnlockDiagnosticVMOptions.

C

false

false

-XX:+/-CRaCTraceStartupTime

Trace the startup time. This needs to be set already during the checkpoint creation.

C

false

false

-XX:+/-CRaCDoThrowCheckpointException

Throw CheckpointException if resource handle is found that can’t be checkpointed.

C

true

true

-XX:+/-CRaCPauseOnCheckpointError

Pauses the checkpoint when a problem is found on the JVM level.

C

false

false

-XX:CRaCMaxHeapSizeBeforeCheckpoint=<value>

The maximum size of the heap before the checkpoint. By default, this equals to -Xmx.

C

0

0

-XX:CPUFeatures=<value>

The CPU feature set. Use -XX:CPUFeatures=0xnumber with -XX:CRaCCheckpointTo when you get an error during -XX:CRaCRestoreFrom on a different machine (with another architecture).

This option is only available on x86.

  • native is the default (and fastest)

  • ignore disables the CPU features check

  • generic is compatible but slower compared to native

C

native

native

-XX:+/-ShowCPUFeatures

Show the features of this CPU to be possibly used for the -XX:CPUFeatures=0xnumber option. This option is best used with:

 
java -XX:+ShowCPUFeatures -version

This option is only available on x86.

N/A

false

false

-XX:+/-IgnoreCPUFeatures

EXPERIMENTAL! Flag defining to continue to run after -XX:CRaCRestoreFrom finds out some CPU features are missing.

This option is only available on x86.

R

false

false

CRIU Engine Options

These are a few of the most used options that are available for -XX:CRaCEngineOptions=<value> when using the CRIU Based Engine. For the full list, start your JVM with -XX:CRaCEngine=criu -XX:CRaCEngineOptions=help. The CRIU Engine is only available in OpenJDK Builds and Azul Zulu Builds of OpenJDK.

Engine Option C/R [1]Use at Checkpoint (C) and/or Restore (R) Zulu

keep_running=<true/false>

Keep the process running after the checkpoint or kill it.

C

false

direct_map=<true/false>

On restore, map process data directly from saved files. This may speedup the restore but the resulting process will not be the same as before the checkpoint.

R

true

compression=<true/false>

Enable image compression with default parameters. Can be used for the creation of a checkpoint, on restore compression is detected automatically.

C

false

args=<string>

Free space-separated arguments, passed directly to the engine executable, e.g. --arg1 --arg2 --arg3.

This can be used to set:

  • Logging verbosity: -v <level> with the level between 0 (off) and 4 (debug).

  • Log file: -o <filename>.

C and R

empty string

Warp Engine Options

These are the options that are available for -XX:CRaCEngineOptions=<value> when using the Warp Engine. You can also retrieve this list from the JVM with -XX:CRaCEngine=warp -XX:CRaCEngineOptions=help.

Warp Engine Options Available in Community Availability (CA) Builds

Engine Option C/R [1]Use at Checkpoint (C) and/or Restore (R) Zulu Zing

keep_running=<true/false>

On checkpoint, keep the application running after the checkpoint or kill it.

C

false

false

load_concurrency=<unsigned int>

A hint to use the specified number of threads for concurrently executed tasks. Setting this to 0 disables work in the background if the configuration supports this, otherwise the concurrency is set to 1 and a warning is emitted.

Note
 This setting applies to all tasks that can be executed in parallel. The concurrent option, available in the Warp Engine in SA Builds, as described here, applies to Concurrent Memory Loading.

C and R

number of CPU cores

1

direct_map=<true/false>

On restore, map process data directly from saved files. This may speed up the restore but the resulting process will not be the same as before the checkpoint.

R

true

true

copy_buffer_size=<bytes> [2]Similar to -Xmx, byte values can be specified with k, M, and G.

Size of buffer used for (interprocess) data copy. It is recommended to keep this lower or equal to CPU Level 2 Cache size.

C and R

1M

1M

max_segment_size=<bytes> [2]Similar to -Xmx, byte values can be specified with k, M, and G.

Maximum size of the memory region stored in the checkpoint image as a single segment.

C

2M

2M

brk_mode=<auto/syscall/function/never>

Defines how to handle the inability to set break memory range ('brk' syscall) without any privileges:

  • auto: Use the best available way of interception (try 'syscall', try 'function', otherwise fail).

  • syscall: Disable the syscall through a seccomp filter.

  • function: Overwrite 'brk' function with a stub.

  • never: Do nothing (application may crash).

R

auto

auto

vdso_always_proxify=<true/false>

Incompatible symbols in vDSO (e.g. when checkpoint runs on a different kernel version) are handled through vDSO proxification. Normally this is performed only when a mismatch is detected, but for testing purposes an option to always introduce the proxy is exposed.

R

false

false

save_zero_pages=<true/false>

By default, memory pages that contain only zeroes are omitted from the checkpoint image. With true, all accessible memory regions are stored, inflating the image size.

C

false

false

min_zero_gap=<bytes> [2]Similar to -Xmx, byte values can be specified with k, M, and G.

The shortest continuous sequence of zeroes-only memory that will be separated in the checkpoint image into its own empty section. This option is applicable only if save_zero_pages=false.

C

OS page size

OS page size

log_level=<info/perf>

Logging level for Warp. With perf, extra messages are logged like tracing duration and the sizes of different checkpoint/restore phases.

C and R

info

info

Warp Engine Options available in Subscriber Availability (SA) Builds

Engine Option C/R [1]Use at Checkpoint (C) and/or Restore (R) Zulu Zing

compression=<true/false>

Enable image compression with default parameters. Can be used for the creation of a checkpoint, has no effect on restore.

C

false

false

compression.algorithm=<string>

Perform image compression on checkpoint using the specified algorithm, on restore the algorithm is detected automatically. Possible values:

  • empty: No compression.

  • default: Use some default algorithm (currently LZ4).

  • LZ4: Use LZ4 compression.

C

""

""

compression.level=<int>

Level of compression. The interpretation of this depends on the selected algorithm. Setting this without enabling image compression has no effect.

C

0

0

encryption.key.file=<path>, encryption.key.env=<string>

Location of a hex-encoded key to be used for image encryption or decryption:

  • file: path to a file containing the key and optionally one newline symbol in the end

  • env: name of an environment variable with the key.

The options are mutually exclusive.

C and R

""

""

encryption.algorithm=<string>

Use the specified algorithm for encryption on checkpoint. On restore the algorithm is detected automatically.

Possible values:

  • AES-<size>-<mode>: AES with a key of:

    • <size> bits (128, 192, 256)

    • <mode> mode of operation (CTR, CBC)

C

AES-128-CTR

AES-128-CTR

concurrent=<true/false>

Enables Concurrent Memory Loading (CML) to let application threads continue before the whole memory is restored. If a thread tries to access a yet-not-restored memory it gets blocked until the memory is restored. Should be specified on restore, has no effect on checkpoint.

R

false

true

concurrent.on_demand=<true/false>

Enable Concurrent Memory Loading (CML) of data during concurrent restore, in addition to loading the data in a background thread.

R

true

true

concurrent.on_demand_minimal=<true/false>

When using Concurrent Memory Loading (CML) of data into multi-mapped memory, the thread can update all secondary mappings (not minimal) or update only the mapping that was accessed (minimal).

R

true

true

optimization.profiling_runs=<unsigned int>

Perform the specified number of profiling runs: in each run a restore is performed and the order in which pages are loaded is recorded. Each profiling run ends when the whole memory has been loaded. The gathered statistics can then be used to speed-up restore.

C and R

0

Not supported

numa=<true/false>

Record and restore NUMA status.

C and R

false

Not supported

numa.force_store_page_info=<true/false>

Store per-page information even if the executing machine has only a single NUMA node. Has no effect if NUMA status recording is not enabled.

C

false

Not supported

s3.endpoint=<url>

Can be set to use a custom S3-compatible storage accessible via the specified HTTP endpoint instead of AWS S3. See Using S3 Storage.

C and R

s3.log.level=<off/fatal/error/warn/info/debug/trace>

S3 logging level.

C and R

off

off

s3.log.prefix=<string>

Prefix for file storage of the AWS S3 log.

C and R

aws_sdk_

aws_sdk_

s3.upload.part_size=<bytes> [2]Similar to -Xmx, byte values can be specified with k, M, and G.

Size in bytes of each part on which the image is split when uploading to S3. S3 supports up to 10000 parts per connection, 5 MiB - 5 GiB each. If the image has more than 50 GiB you may need to increase the default part size (designated by 0).

C

0

0

s3.download.part_size=<bytes> [2]Similar to -Xmx, byte values can be specified with k, M, and G.

Similar to upload part size but used when downloading an image.

R

0

0

s3.connections=<unsigned int>

The number of connections that should be used to upload/download an image to/from S3. 0 designates some default number.

C and R

0

0

s3.image_selection_policy=<single/last/random/mostbits>

Policy used for storing and retrieving images from S3:

  • single: Image is uploaded with a deterministic AWS object key. On download, the single image is fetched, if present. This reduces restore times by not requiring listing of available images.

  • last: On upload, a unique suffix is appended to the image location (object key). On download, the image with matching location (without considering the suffix) and the latest modification date is selected.

  • random: On upload, a unique suffix is appended to the image location (object key). On download, a randomly-selected image matching image location (without considering the suffix) is used.

  • mostbits: Same as random but when downloading the image with most similar bitmask will be used.

C and R

single

single

s3.image_bitmask=<hex>

Note
 This option is included only for completeness and consistency with -XX:CRaCEngineOptions=help. The JVM itself generates the value and sets the value for this option based on the currently used CPU Features. You should NOT set this option manually.

On checkpoint, this option sets a bitmask to be saved in the S3 object key. On restore the behavior depends on s3.image_selection_policy:

  • single: The bitmask must exactly match the bitmask used during checkpoint.

  • last, random, mostbits: The image is selected only if a bitwise AND of the current bitmask and the bitmask set during checkpoint is equal to the checkpoint bitmask. In other words, if a bit was set on checkpoint it must be set now. If the bitmap lengths differ, the excess bits in the end are considered to be zero.

The intended purpose is to encode capabilities of the system where checkpoint or restore if performed: on checkpoint the minimal required capabilities should be recorded, and on restore they are compared against the available capabilities.

C and R

""

""

Deprecated Command-Line Options

With the Zulu release of July 2025, multiple CRaC engine options got deprecated and are now incorporated into CRaCEngineOptions. These options can still be used, but will be removed in the release of July 2026.

Command Line Option C/R [1]Use at Checkpoint (C) and/or Restore (R) Zulu

-XX:+/-CRaCKeepRunning

Flag defining to not terminate the process after the checkpoint.

Is replaced by:
-XX:CRaCEngineOptions=keep_running=<true/false>

C

false

-XX:+/-CRaCConcurrentMemoryLoading

Used for restore to start the restored process before the image is fully unpacked into memory. As applications usually don’t require all data to perform some useful work, this can improve the startup lag.

Direct memory mapping (non-compressed) is extremely fast compared to regular loading. Compressed images are slower as they need to be uncompressed. -XX:+CRaCConcurrentMemoryLoading may improve the time to the first operation after restore for large images. For small images, the effect may be negative.

Is replaced by:
-XX:CRaCEngineOptions=concurrent=<true/false>

R

false

-XX:+/-CRaCDirectMapImage

Flag to define if the checkpoint image is mapped into memory directly (true), or read into anonymous memory map (false). Direct mapping usually results in faster restore, but operations accessing the memory for the first time might experience decreased performance as the content is paged-in lazily.

Is replaced by:
-XX:CRaCEngineOptions=direct_map=<true/false>

R

true

XX:CRaCOptimizeImage=<value>

After checkpoint, the image can be automatically reordered, based on the loading order in the profiling runs. This option sets the number of profiling runs. The default value of 0 means no optimization.

With Warp, you can use the option -XX:CRaCOptimizeImage=N to perform N training runs to create checkpoints. After the checkpoint image is created, Warp iteratively performs N restores and determine the optimal layout of the image.

Is replaced by:
-XX:CRaCEngineOptions=optimization.profiling_runs=N

C

0

-XX:+/-CRaCImageCompression

Compress the CRaC image during the checkpoint. Upon restore, the compressed format is detected automatically.

Is replaced by:
-XX:CRaCEngineOptions=compression=<true/false>

C

false

System Properties

The following system properties for CRaC can be set.

System Property C/R [1]Use at Checkpoint (C) and/or Restore (R) Zulu Zing

jdk.crac.resource-policies=<value>

See File Descriptor Policies

C

null

null

jdk.crac.collect-fd-stacktraces=<true/false>

See Debugging Coordinated Restore at Checkpoint Failures > File Descriptors in Java Code

C

false

false

jdk.crac.trace-startup-time=<true/false>

Print startup time values to track how long the Java-side of the restore takes.

This prints to stdout:

  • STARTUPTIME <SYSTEM NANOTIME> restore

  • STARTUPTIME <SYSTEM NANOTIME> restore-finish

C

false

false

jdk.crac.globalContext.impl=<value>

This property has two options:

  • OrderedContext (default): Lets you register the resource when the checkpoint/restore is already executing, but this Resource’s beforeCheckpoint() and afterRestore() methods won’t be called during this checkpoint/restore.

  • BlockingOrderedContext: Lets you assert that there is no new Resource registered during execution of the checkpoint/restore. The thread trying to register a new resource is blocked (this can lead to a deadlock).

C

OrderedContext

OrderedContext

jdk.crac.enable-recompilation=<true/false>

Flag to define whether CRaC should record code decompiled during checkpoint/restore and schedule its recompilation afterwards. This can’t be changed after the first checkpoint starts. Disabling this may make JVM run a bit slower after the restore compared to before the checkpoint.

C

true

Not supported

jdk.crac.recompilation-delay-ms=<milliseconds>

If jdk.crac.enable-recompilation is true, this setting allows delaying finishing recording decompilations by the specified amount of time (values <= 0 mean there will be no delay). Larger values allow more decompilations triggered by possible changes inflicted by checkpoint/restore to be recorded and recompiled but delay all other recompilations.

C and R

10

Not supported

Set these properties when you execute Java, for example:

 
java -XX:CRaCCheckpointTo=... \
    -Djdk.crac.resource-policies=/path/to/file.yml \
    -jar my_app.jar arg1 arg2