Command-Line Utility Reference

Initializes a new PostgreSQL data directory for BSim and prepares it for use. The command-line must include a path to the data directory, which is created if it does not already exist (an existing directory must be empty). The database is initialized, the configuration and authentication files are tuned, the server certificate is installed, and the BSim lshvector extension is enabled; the server is then left stopped. Use start to run it. The PostgreSQL administrative role (the global --user option, defaulting to the invoking user) is created with admin privileges.

--os-user <account> - specifies the operating-system account that will own the data directory and run the postgres process. This option may only be used when running as root (via sudo) and is required in that case; all data-directory files are created owned by this account. When not running as root the option must be omitted and the invoking user becomes the owner. This OS account is distinct from the PostgreSQL administrative role established by the --user option.

--keystore|-k </keystore-path> - specifies a password-protected PKCS#12 (or JKS) key store containing a CA-signed server certificate and private key (for example, one produced by the certTool utility). The key store password is prompted for on the console; the certificate chain and private key are extracted to server.crt and server.key within the data directory. When a key store is supplied the server listens on all interfaces and accepts remote connections. If --keystore is omitted, a self-signed certificate restricted to the loopback interface is generated, the server binds to localhost only, and remote client access is disabled (a warning is issued for those options which only affect remote access and therefore have no effect). The authentication type given by --auth still applies to local (loopback) connections and is recorded, so that it also applies to remote clients should remote access be enabled later with --keystore.

--auth|-a <type> - specifies the authentication type ( password | pki | trust): password for password authentication (default mode), pki for authentication using public key certificates, and trust for no authentication. Use of trust mode is highly discouraged. With the pki setting, both the --cafile and the global --cert options must also be provided; the admin user's Distinguished Name (DN) and Common Name (CN) are obtained from the --cert certificate and no --dn option is accepted. The authentication type is recorded within the data directory (in bsim-config.properties, which must not be edited) so that later commands such as adduser and status can determine how the server was configured.

A server initialized with --auth pki identifies each user by their full Distinguished Name, which is registered within pg_ident.conf and matched against the certificate a client presents. A Common Name alone is not a unique identity - it is chosen by whoever issues a certificate, and two authorities within the same root.crt may issue certificates carrying the same Common Name to different people. A server which was initialized by Ghidra 12.1.x or older continues to match only the Common Name, because the user entries it already holds were registered that way; see adduser.

--noLocalAuth - used together with the --auth option causes authentication to not be required for local (loopback) connections.

Only local authentication is affected — the --auth mode is still recorded, still governs remote connections should a key store later enable them, and still determines what adduser establishes for each user (a password, or a certificate identity mapping). Those credentials are therefore already in place if configure later enables remote access; without them every user would be unable to authenticate at that point. Local authentication becomes subject to the configured mode once a --keystore is supplied.

--cafile|-ca </cafile-path> - specifies an absolute path to a certificate authority file and is required for --auth pki. This file contains the certificate authorities used to verify client certificates and is installed within the data directory as root.crt. PostgreSQL requires it to be an unencrypted PEM file (Base64 encoded certificates concatenated together) which itself provides a complete chain of trust, since the server does not look beyond this file when verifying a certificate a client presents. It is fully loaded and validated each time it is used:

• a certificate which is not a certificate authority, or an authority whose chain of trust cannot be traced to a root certificate authority within the same file, is reported as an error (all such certificates are identified);

• an expired certificate authority is reported as a warning, as is an authority which is not permitted to sign certificates.

The global --cert certificate is verified against these same authorities, exactly as the server will verify it, so that a certificate the server would reject is identified before the configuration takes effect.

--port|-p <portnum> - specifies the port that the PostgreSQL server listens to (default 5432). For non-default ports, URLs and other command-lines connecting to the server must explicitly specify the port. Use configure to change the port after initialization if needed. The default port 5432 will be used if a invalid value is specified.

Changes the configuration of a previously initialized server. The path to the data directory must be specified and the server must be running. Accepts the same options as init except --os-user: --auth, --noLocalAuth, --cafile, --keystore, and the global --port. Supplying --keystore installs a new server certificate and enables remote access; omitting it preserves the current binding.

Supplying --cafile replaces the installed certificate authorities (root.crt) and, because every client certificate must then be issued by one of the incoming authorities, requires the admin user's --cert so that it can be verified against them first. Omitting the option retains the authorities already installed, which are re-loaded and re-validated so that a chain which has become stale (an expired authority) is reported.

The server is left running and the changes take effect when it is next restarted. The server must be running because any change to the authentication requires that the invoking user first authenticate with the admin role (using the authentication currently in effect, so the global --user and --cert options may be needed), and because any credential the change requires must be put in place before the restart:

• Changing to --auth password when the admin user has no database password established will prompt for a new password on the console and set it. Any other existing user may also lack a password and can be given one with resetpassword after the restart.

• Changing to --auth pki requires the admin user's certificate (the global --cert option) and establishes their PostgreSQL identity mapping from it. As with init, no --dn option is accepted: the Distinguished Name is taken from the certificate so that the mapping cannot disagree with the certificate which will be presented, and it is verified against the --cafile certificate authority. Any other existing user requires a mapping too, which can be added with adduser and its --dn option after the restart.

Older BSim PostgreSQL databases with PKI authentication relied on user's Common Name (CN), whereas newer databases rely on the user's Distinguished Name (DN) which is more unique and generally contains a CN. This is a property of the server and configure preserves it: a server which already uses PKI keeps matching whichever it was configured for, since the identity mappings registered for its users cannot be re-derived (each user's certificate is held by that user). A server which is being changed to PKI has no such mappings and so is configured to match the full Distinguished Name (DN). The one in effect is reflected by the commands: status, and listusers.

NOTE: a change to --auth trust removes authentication entirely and so does not require the admin role to be authenticated. This is the means of recovering from a forgotten password or an unavailable certificate: change to trust, restart, re-establish the credential (resetpassword), then change back.

Starts a previously initialized PostgreSQL server. The path to the data directory must be provided and must already have been initialized with init; otherwise the command fails with guidance to run init. This command takes no options and performs no configuration. If a service has been installed for the data directory (see install-service) the request is delegated to systemctl and must be run as root.

Stops a running PostgreSQL server. The path to the data directory must be provided. By default, shutdown waits until existing connections are closed. If a service is installed the request is delegated to systemctl and must be run as root.

--force|-f - causes existing connections to be forcibly closed and the server to shut down immediately.

Restarts a previously initialized PostgreSQL server (equivalent to a stop followed by a start), performing no configuration. The path to the data directory must be provided. If a service is installed the request is delegated to systemctl and must be run as root.

--force|-f - uses fast shutdown mode for the stop phase (existing connections are forcibly closed).

Reports the status of a server: the data directory owner, the port, the authentication type in effect (and, for --auth pki, whether users are identified by their full Distinguished Name or by their Common Name alone), whether remote access is enabled, whether a service is installed (and enabled), and the running state. The path to the data directory must be provided.

Installs a systemd service that supervises the server for the specified (initialized) data directory, enabling it to start automatically at boot. Only supported on Linux and must be run as root (via sudo). The service runs the postgres process as the data directory owner. The server must not be running when the service is installed. Once installed, the start, stop, restart, and status commands operate through the service (start/stop/restart then require root).

Stops, disables, and removes the systemd service previously installed for the specified data directory (Linux, root only). The data directory and its contents are left intact.

Give a new user permission to access the PostgreSQL server. The path to the actively used data directory and a single username must be specified. The server must be running. New users are given user (read-only) privileges, unless a subsequent changeprivilege command is used.

--dn|-dn <distinguished-name> - specifies the Distinguished Name (DN) of the new user, which is required if the database enabled --auth pki. This option can be used to provide a Distinguished Name to a pre-existing user, if the PostgreSQL server's authentication strategy is changed.

IMPORTANT: The specified DN must match exactly how it is specified within the user's certificate that they will use when connecting to the PostgreSQL server. It is case-senstive and any spaces must be preserved. Give it in RFC 2253 form - the form in which the server renders the certificate subject - which for a given certificate is reported by:

openssl x509 -noout -subject -nameopt RFC2253 -in certfile

What is registered for the user depends upon how the server itself was configured (see init). Normally the full Distinguished Name is registered; for a server initialized by Ghidra 12.1.x or older only the Common Name contained within the supplied Distinguished Name is registered (and the Distinguished Name must therefore contain one). Either way the name actually registered is reported, and can be reviewed later with listusers.

Remove access to the PostgreSQL server for a specific user. The path to the actively used data directory and a single username must be specified. The server must be running.

List all users defined on the PostgreSQL server along with their role. The path to the actively used data directory must be specified, and the server must be running. Each user is reported as admin if it has administrative (superuser) privileges, or user otherwise (see changeprivilege).

If the server is configured for --auth pki, the certificate name registered for each user within pg_ident.conf is listed as well - their full Distinguished Name, or their Common Name for a server which matches only that (see init) - with the column heading indicating which. A user shown as <none registered> has no certificate mapping and will be unable to authenticate; one can be established with adduser and its --dn option.

Reset the password for a user. A single user must be specified, and the PostgreSQL server must be running. The password will be reset to 'changeme'.

Change access privilege for a user. A single user must be specified followed by admin or user, and the PostgreSQL server must be running.

These options apply to all the bsim_ctl commands that connect to an active PostgreSQL server: init, adduser, dropuser, listusers, resetpassword, and changeprivilege.

--port|-p <portnum> - specifies the port on which to connect with the PostgreSQL server.

--user|-u <username> - specifies a user name to use when connecting to the PostgreSQL server.

--cert </certfile-path> - provides the absolute file path to the user's certificate when connecting to a PostgreSQL server that requires PKI authentication.

--verbose|-v  - enable verbose logging of all system commands executed during processing (e.g., pg_ctl execution).

Creates a new empty repository. A URL and configuration template (config_template) is required. The new database name is taken from the path element of the URL. See “Creating a Database” for more details and discussion on configuration template use. See “Creating Database Templates“ if a standard template will not suffice.

Supported configuration templates (config_template) are defined within the Ghidra installation in XML form. The following configurations are currently defined: (large_32, medium_32, medium_64, medium_cpool, medium_nosize).

--name|-n - specifies a formal, more descriptive, name for the repository that can be used for the BSim client display.

--owner|-o - gives a descriptive name for the owner of the repository and/or the data it will contain.

--description|-d - specifies a short string describing the intended contents of the new repository.

--nocallgraph - disables storing call relationships between ingested functions. Default is to store call relationships.

Deletes the specified repository. A BSim server URL is required. The database name is taken from the path element of the URL.

--force|-f - skips the confirmation dialog and deletes the database. Default is to ask for confirmation.

Change the global name, owner, or description metadata associated with a BSim server. A BSim server URL is required.

--name|-n - specifies a formal, more descriptive, name for the repository that can be used for the BSim client display.

--owner|-o - gives a descriptive name for the owner of the repository and/or the data it will contain.

--description|-d - specifies a short string describing the intended contents of the new repository.

Show the global name, owner, and description metadata associated with a BSim server. A BSim server URL is required.

Specify a new executable category to be included with generated metadata. A BSim server URL and the name of the new category are required. This only affects future ingest commands. Executables that have already been ingested are unaffected, although they can be adjusted with an generateupdates command.

date - indicates the new category holds date/time information.

Specify a new function tag to be included with generated metadata. A BSim server URL and the name of the new tag are required. This only affects future ingest commands. Functions that have already been ingested are unaffected, although they can be adjusted with an generateupdates command.

Delete the main signature index from a BSim repository (in preparation for new ingest). A BSim repository URL is required. Normal queries will not complete or will be extremely slow.

NOTE: Not supported by H2 file database

Recreate the main signature index (that had previously been dropped) for a BSim repository. A BSim server URL is required. After this command completes, normal function queries should be fast.

NOTE: Not supported by H2 file database

Instruct a restarted BSim server to preload pages from the main signature index and function table into RAM. This avoids slow random access disk reads on initial queries. A BSim server URL is required.

NOTE: Not supported by Elasticsearch or H2 file databases

Generates function signatures and metadata for all program files retrieved from a Ghidra Server repository or project as specified by a Ghidra URL. The generated signatures may be retained as XML "sigs_" files within a specified XML storage directory and/or committed to a specified BSim database specified with the --bsim option. If an XML storage directory is not specified, a BSim URL must be specified to which the data will be committed.

The --config|-c <config-template> option may be specified when generating XML "sigs_" signature files in the absence of a BSim database (see createdatabase for supported configurations). The generated files will be written to the specified XML storage directory. Creation of the signature files can also be achieved by specifying the --bsim option instead of the --config option.

The --overwrite option may be specified when an XML storage directory has also been specified to allow conflicting signature files to be overwritten.

The --commit option may be specified when a BSim URL has also been specified to allow generated signatures to be committed to the BSim database. This option is implied when a BSim URL has been specified without an XML storage directory.

Commit previously generated signatures and metadata (see generatesigs) to a BSim repository. A URL specifying the BSim repository and a path to a directory containing the "sigs_" XML files to commit are required.

--override <ghidraURL> - causes any Ghidra repository/project URL, describing the storage repository and path of executables that was recorded in the "sigs_" XML files during signature generation, to be overridden during the commit operation with the specified Ghidra URL.

Generates updated function metadata for program files from a Ghidra Server repository or project, as specified by a Ghidra URL, which previously had signature and metadata generated (see generatesigs). Only metadata: names, function tags, categories, etc. are changed. Signatures are not affected. The generated updates may be retained as XML "update_" files within a specified XML storage directory and/or committed to a specified BSim database specified with the --bsim option. If an XML storage directory is not specified, a BSim URL must be specified to which the data will be committed.

The --config|-c <config-template> option may be specified when generating XML "update_" files in the absence of a BSim database (see createdatabase for supported configurations). The generated files will be written to the specified XML storage directory. Creation of the update files can also be achieved by specifying the --bsim option instead of the --config option.

The --overwrite option may be specified when an XML storage directory has also been specified to allow conflicting update files to be overwritten.

The --commit option may be specified when a BSim URL has also been specified to allow generated updates to be committed to the BSim database. This option is implied when a BSim URL has been specified without an XML storage directory.

Update a BSim repository with previously generated update metadata (see generateupdates). A URL specifying the BSim repository and a path to a directory containing the "update_" XML files to commit are required.

List all executable program records within a specified BSim database repository which satisfy the specified criteria. A BSim URL specifying the repository must be provided, and one of two options, --md5 or --name , that indicate the specific executable must also be given. All matching executable records will be listed.

--md5|-m - specifies an executable via its MD5 checksum as 32 hexidecimal digits.

--name|-n - specifies an executable name which may match one or more executable records.

--arch|-a - specifies an architecture as a Ghidra processor id which will be used to filter executables.

--compiler - specifies a compiler specification id which will be used to filter executables.

--sortcol|-s - Specifies which display column should be used to sort the results (md5 | name; default: md5).

--limit|-l - specifies the maximum number of executables to be listed which match the search criteria (default=20, a value of 0 indicates no limit).

--includelibs - If specified, executable records which correspond to a referenced Library will be included. Such records have a fabricated MD5 which is based on its name.

List all BSim databases hosted by a server. Every discovered database that appears to be a BSim database (i.e., that contains the expected key BSim tables such as vectable and archtable, or the equivalent Elasticsearch indexes) is reported along with the details that were originally supplied when it was created with createdatabase: its formal name, owner, description, whether call-graph information is tracked, and any executable categories, function tags, and date column that have been defined.

For the postgresql, elastic, and https URL forms the /<dbname> element is optional (see “BSim Database URLs”). When it is omitted, all BSim databases hosted by the server are listed; when a database name is supplied, only that single database is listed. A file (H2) URL must always specify a specific database.

Get the total number of executable program records within a specified BSim database repository which satisfy the specified criteria. A BSim URL specifying the repository must be provided, and one of two options, --md5 or --name, that indicate the specific executable must also be given. All matching executable records will be listed.

--md5|-m - specifies an executable via its MD5 checksum as 32 hexidecimal digits.

--name|-n - specifies an executable name which may match one or more executable records.

--arch|-a - specifies an architecture as a Ghidra processor id which will be used to filter executables.

--compiler - specifies a compiler specification id which will be used to filter executables.

--includelibs - If specified, executable records which correspond to a referenced Library will be included. Such records have a fabricated MD5 which is based on its name.

Remove all records associated with a specific executable from a BSim repository. A BSim URL specifying the repository must be provided, and one of two options, --md5 or --name, that indicate the specific executable must also be given. All associated executable and function records are removed. If an executable cannot be uniquely identified an error will result.

--md5|-m - specifies an executable via its MD5 checksum as 32 hexidecimal digits.

--name|-n - specifies an executable name which may match one or more executable records.

--arch|-a - specifies an architecture as a Ghidra processor id, when the --name option is not enough to uniquely specify the executable.

--compiler - specifies a compiler id string, when the --name option is not enough to uniquely specify the executable.

List all function records associated with a specific executable from a BSim repository. A BSim URL specifying the repository must be provided, and one of two options, --md5 or --name, that indicate the specific executable must also be given. All associated executable and function records are listed. If an executable cannot be uniquely identified an error will result.

--md5|-m - specifies an executable via its MD5 checksum as 32 hexidecimal digits.

--name|-n - specifies an executable name which may match one or more executable records.

--arch|-a - specifies an architecture as a Ghidra processor id, when the --name option is not enough to uniquely specify the executable.

--compiler - specifies a compiler id string, when the --name option is not enough to uniquely specify the executable.

--printselfsig - If specified, each function listed will be prefixed by a calculated self-significance score. This score is expressed as a floating-point value.

--callgraph - If specified, a list of all library functions called by the identified executable will be listed after the function list.

--printjustexe - If specified, only a summary of the executable will be displayed. If --callgraph was also specified only the called libraries will be listed and not the specified functions.

--maxfunc - specifies the maximum number of functions to be listed which correspond to the identified executable (default=1000, a value of 0 indicates no limit).

Dump signature and metadata from a BSim repository for a specific executable to a "sigs_" XML file. A BSim server URL and a path to a directory where the new file will be stored must be given. One of two options, --md5 or --name, that specify the particular executable must also be given. If an executable cannot be uniquely identified an error will result.

--md5|-m - specifies an executable via its MD5 checksum as 32 hexidecimal digits.

--name|-n - specifies an executable name which may match one or more executable records.

--arch|-a - specifies an architecture as a Ghidra processor id, when the --name option is not enough to uniquely specify the executable.

--compiler - specifies a compiler specification id, when the --name option is not enough to uniquely specify the executable.

Change the BSim database password of the connecting user. A BSim URL specifying the repository must be provided. The user must first authenticate with the server using their current credentials, since the password change is issued over the resulting connection. The user whose password is changed is the one used to establish that connection, which is the user named by the URL or by the --user option, and otherwise defaults to the user name reported by the operating system.

Only the postgresql, elastic, and https URL forms are supported, and the server must be configured for password authentication (see “Security and Authentication”). A file (H2) database has no user password and is not supported.

The new password is prompted for on the console and must be entered twice. If the two entries do not match the prompt is repeated. A password may not be specified on the command line.

These options apply to all bsim commands.

--user|-u <username> - specifies a user to masquerade as when connecting to the server.

--cert <certfile-path> - provides a path to the user's certificate when connecting to a server that requires PKI authentication.