crashpad/handler/crashpad_handler.md

crashpad_handler(8)

Name

crashpad_handler—Crashpad’s exception handler server

Synopsis

crashpad_handler [OPTION…]

Description

This program is Crashpad’s main exception-handling server. It is responsible for catching exceptions, writing crash reports, and uploading them to a crash report collection server. Uploads are disabled by default, and can only be enabled by a Crashpad client using the Crashpad client library, typically in response to a user requesting this behavior.

On macOS, this server may be started by its initial client, in which case it performs a handshake with this client via a pipe established by the client that is inherited by the server, referenced by the --handshake-fd argument. During the handshake, the server furnishes the client with a send right that the client may use as an exception port. The server retains the corresponding receive right, which it monitors for exception messages. When the receive right loses all senders, the server exits after allowing any upload in progress to complete.

Alternatively, on macOS, this server may be started from launchd(8), where it receives the Mach service name in a --mach-service argument. It checks in with the bootstrap server under this service name, and clients may look it up with the bootstrap server under this service name. It monitors this service for exception messages. Upon receipt of SIGTERM, the server exits after allowing any upload in progress to complete. SIGTERM is normally sent by launchd(8) when it determines that the server should exit.

On Windows, clients register with this server by communicating with it via the named pipe identified by the --pipe-name argument. Alternatively, the server can inherit an already-created pipe from a parent process by using the --initial-client-data mechanism. That argument also takes all of the arguments that would normally be passed in a registration message, and so constitutes registration of the first client. Subsequent clients may then register by communicating with the server via the pipe. During registration, a client provides the server with an OS event object that it will signal should it crash. The server obtains the client’s process handle and waits on the crash event object for a crash, as well as the client’s process handle for the client to exit cleanly without crashing. When a server started via the --initial-client-data mechanism loses all of its clients, it exits after allowing any upload in progress to complete.

On Windows, this executable is built by default as a Windows GUI app, so no console will appear in normal usage. This is the version that will typically be used. A second copy is also made with a .com extension, rather than .exe. In this second copy, the PE header is modified to indicate that it’s a console app. This is useful because the .com is found in the path before the .exe, so when run normally from a shell using only the basename (without an explicit .com or .exe extension), the .com console version will be chosen, and so stdio will be hooked up as expected to the parent console so that logging output will be visible.

On Linux/Android, the handler may create a crash dump for its parent process using --trace-parent-with-exception. In this mode, the handler process creates a crash dump for its parent and exits. Alternatively, the handler may be launched with --initial-client-fd which will start the server connected to an initial client. The server will exit when all connected client sockets are closed.

It is not normally appropriate to invoke this program directly. Usually, it will be invoked by a Crashpad client using the Crashpad client library, or started by another system service. On macOS, arbitrary programs may be run with a Crashpad handler by using run_with_crashpad(1) to establish the Crashpad client environment before running a program.

Options

• --annotation=KEY=VALUE

  Sets a process-level annotation mapping KEY to VALUE in each crash report that is written. This option may appear zero, one, or multiple times.

  Most annotations should be provided by the Crashpad client as module-level annotations instead of process-level annotations. Module-level annotations are more flexible in that they can be modified and cleared during the client program’s lifetime. Module-level annotations can be set via the Crashpad client library. Process-level annotations are useful for annotations that the collection server requires be present, that have fixed values, and for cases where a program that does not use the Crashpad client library is being monitored.

  Breakpad-type collection servers only require the "prod" and "ver" annotations, which should be set to the product name or identifier and product version, respectively. It is unusual to specify other annotations as process-level annotations via this argument.

• --database=PATH

  Use PATH as the path to the Crashpad crash report database. This option is required. Crash reports are written to this database, and if uploads are enabled, uploaded from this database to a crash report collection server. If the database does not exist, it will be created, provided that the parent directory of PATH exists.

• --handshake-fd=FD

  Perform the handshake with the initial client on the file descriptor at FD. Either this option or --mach-service, but not both, is required. This option is only valid on macOS.

• --initial-client-data=HANDLE_request_crash_dump,HANDLE_request_non_crash_dump,HANDLE_non_crash_dump_completed,HANDLE_first_pipe_instance,HANDLE_client_process,Address_crash_exception_information,Address_non_crash_exception_information,Address_debug_critical_section

  Register the initial client using the inherited handles and data provided. For more information on the argument’s format, see the implementations of CrashpadClient and ExceptionHandlerServer. Either this option or --pipe-name, but not both, is required. This option is only valid on Windows.

  When this option is present, the server creates a new named pipe at a random name and informs its client of the name. The server waits for at least one client to register, and exits when all clients have exited, after waiting for any uploads in progress to complete.

• --initial-client-fd=FD

  Wait for client requests on FD. Either this option or --trace-parent-with-exception, but not both, is required. The handler exits when all client connections have been closed. This option is only valid on Linux platforms.

• --mach-service=SERVICE

  Check in with the bootstrap server under the name SERVICE. Either this option or --handshake-fd, but not both, is required. This option is only valid on macOS.

  SERVICE may already be reserved with the bootstrap server in cases where this tool is started by launchd(8) as a result of a message being sent to a service declared in a job’s MachServices dictionary (see launchd.plist(5)). The service name may also be completely unknown to the system.

• --metrics-dir=DIR

  Metrics information will be written to DIR. This option only has an effect when built as part of Chromium. In non-Chromium builds, and in the absence of this option, metrics information will not be written.

• --monitor-self

  Causes a second instance of the Crashpad handler program to be started, monitoring the original instance for exceptions. The original instance will become a client of the second one. The second instance will be started with the same --annotation, --database, --monitor-self-annotation, --no-rate-limit, --no-upload-gzip, and --url arguments as the original one. The second instance will always be started with a --no-periodic-tasks argument, and will not be started with a --metrics-dir argument even if the original instance was.

  Where supported by the underlying operating system, the second instance will be restarted should it exit before the first instance. The second instance will not be eligible to be started asynchronously.

• --monitor-self-annotation=KEY=VALUE

  Sets a module-level annotation mapping KEY to VALUE in the Crashpad handler. This option may appear zero, one, or more times.

  If --monitor-self is in use, the second instance of the Crashpad handler program will find these annotations stored in the original instance and will include them in any crash reports written for the original instance.

  These annotations will only appear in crash reports written for the Crashpad handler itself. To apply a process-level annotation to all crash reports written by an instance of the Crashpad handler, use --annotation instead.

• --monitor-self-argument=ARGUMENT

  When directed by --monitor-self to start a second instance of the Crashpad handler program, the second instance will be started with ARGUMENT as one of its arguments. This option may appear zero, one, or more times. This option has no effect in the absence of --monitor-self.

  This supports embedding the Crashpad handler into a multi-purpose executable that dispatches to the desired entry point based on a command-line argument. To prevent excessive accumulation of handler processes, ARGUMENT must not be --monitor-self.

• --no-identify-client-via-url

  Do not add client-identifying fields to the URL. By default, "prod", "ver", and "guid" annotations are added to the upload URL as name-value pairs "product", "version", and "guid", respectively. Using this option disables that behavior.

• --no-periodic-tasks

  Do not scan for new pending crash reports or prune the crash report database. Only crash reports recorded by this instance of the Crashpad handler will become eligible for upload in this instance, and only a single initial upload attempt will be made.

  This option is not intended for general use. It is provided to prevent multiple instances of the Crashpad handler from duplicating the effort of performing the same periodic tasks. In normal use, the first instance of the Crashpad handler will assume the responsibility for performing these tasks, and will provide this argument to any second instance. See --monitor-self.

• --no-rate-limit

  Do not rate limit the upload of crash reports. By default uploads are throttled to one per hour. Using this option disables that behavior, and Crashpad will attempt to upload all captured reports.

• --no-upload-gzip

  Do not use gzip compression for uploaded crash reports. Normally, the entire request body is compressed into a gzip stream and transmitted with Content-Encoding: gzip. This option disables compression, and is intended for use with collection servers that don’t accept uploads compressed in this way.

• --no-write-minidump-to-database

  Do not write the minidump to database. Normally, the minidump is written to database for upload. Use this option with --write-minidump-to-log to only write the minidump to log. This option is only available to Android.

• --pipe-name=PIPE

  Listen on the given pipe name for connections from clients. PIPE must be of the form \\.\pipe\<somename>. Either this option or --initial-client-data, but not both, is required. This option is only valid on Windows.

  When this option is present, the server creates a named pipe at PIPE, a name known to both the server and its clients. The server continues running even after all clients have exited.

• --reset-own-crash-exception-port-to-system-default

  Causes the exception handler server to set its own crash handler to the system default before beginning operation. This is only expected to be useful in cases where the server inherits an inappropriate crash handler from its parent process. This option is only valid on macOS. Use of this option is discouraged. It should not be used absent extraordinary circumstances.

• --sanitization-information=SANITIZATION-INFORMATION-ADDRESS

  Provides sanitization settings in a SanitizationInformation struct at SANITIZATION-INFORMATION-ADDRESS. This option requires --trace-parent-with-exception and is only valid on Linux platforms.

• --shared-client-connection

  Indicates that the file descriptor provided by --initial-client-fd is shared among mulitple clients. Using a broker process is not supported for clients using this option. This option is only valid on Linux platforms.

• --trace-parent-with-exception=EXCEPTION-INFORMATION-ADDRESS

  Causes the handler process to trace its parent process and exit. The parent process should have an ExceptionInformation struct at EXCEPTION-INFORMATION-ADDRESS. This option is only valid on Linux platforms.

• --url=URL

  If uploads are enabled, sends crash reports to the Breakpad-type crash report collection server at URL. Uploads are disabled by default, and can only be enabled for a database by a Crashpad client using the Crashpad client library, typically in response to a user requesting this behavior. If this option is not specified, this program will behave as if uploads are disabled.

• --use-cros-crash-reporter

  Causes crash reports to be passed via an in-memory file to /sbin/crash_reporter instead of storing them in the database. The database is still used for Crashpad settings. This option is only valid on Chromium OS.

• --write-minidump-to-log

  Write the minidump to log. By default the minidump is only written to database. Use this option with --no-write-minidump-to-database to only write the minidump to log. This option is only available to Android.

• --help

  Display help and exit.

• --version

  Output version information and exit.

Exit Status

• 0

  Success.

• 1

  Failure, with a message printed to the standard error stream.

See Also

catch_exception_tool(1), crashpad_database_util(1), generate_dump(1), run_with_crashpad(1)

Resources

Crashpad home page: https://crashpad.chromium.org/.

Report bugs at https://crashpad.chromium.org/bug/new.

Copyright

Copyright 2014 The Crashpad Authors.

License

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at

http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.