Database Configuration

In order to use PostgreSQL as a BSim server, it must be built with a BSim specific extension, provided as part of the Ghidra installation. Prebuilt servers, like those provided as OS distribution packages, will not work as is with BSim. For users on Linux and macOS, the Ghidra installation provides a script, make-postgres.sh, in the module directory Ghidra/Features/BSim/support that builds both the PostgreSQL server and the BSim extension from source and prepares the installation for use with Ghidra. If not already included in the Ghidra installation, the source distribution file, currently postgresql-15.18.tar.gz, can be obtained from the PostgreSQL website at

The steps to build the PostgreSQL server with the BSim extension then are:

1) If not already present, place the PostgreSQL source distribution file postgresql-15.18.tar.gz in the Ghidra installation at

2) From the command-line, within the same directory, run the script make-postgres.sh

Additional packages or software may need to be installed on the host OS in order for the build to complete successfully, OpenSSL in particular is required for BSim. For the full list of PostgreSQL software dependencies, refer to:

Once the build has completed successfully, the bsim_ctl command-line script is ready to use for starting a server (see “Starting and Stopping the Server”). The PostgreSQL server software will run out of the Ghidra installation at

Other than having the extension itself, a BSim enabled PostgreSQL server is completely standard, and can be configured like any other stand-alone PostgreSQL server. There are no direct restrictions on modifying the configuration values. A default configuration is provided with this installation that has been tuned specifically for the BSim Database application, so in practice there may be little reason to modify it. But there are a few standard configuration values for the server that might need adjusting. See “Additional Configuration”.

A BSim PostgreSQL server is prepared in two steps: a one-time init that creates and configures the data directory, followed by start to run the server. All operations take an absolute path to the chosen data directory. Configuration is performed entirely through the bsim_ctl init and configure commands; the PostgreSQL configuration files are managed on your behalf.

To initialize a new server, run init once against an empty (or not-yet-existing) data directory. This creates the data directory, tunes the configuration, installs the server certificate, and enables the BSim extension, leaving the server stopped:

The data directory is created owned by the operating-system account that will run the server. When init is run as an ordinary user, that user becomes the owner. When run as root (via sudo), the --os-user option is required and names a dedicated, non-root service account that will own the data directory and run the server. All subsequent bsim_ctl commands for a data directory must be run either by that owner or by root.

By default (no --keystore) the server is secured with a self-signed certificate and binds to the loopback interface only, which is appropriate for local single-user use. To accept remote client connections, supply a CA-signed server certificate in a password-protected keystore with the --keystore option (see “Security and Authentication”).

WARNING! Deploying the PostgreSQL server with a self-signed certificate (that is, without the --keystore option) requires every client to waive server authentication for loopback connections, since no client trusts such a certificate. That waiver is only appropriate where every account on the local machine is trusted. See “Security and Authentication” for the VM property involved and what it gives up.

Once initialized, the server is started, stopped, restarted, and queried with:

The start command takes no options and performs no configuration; if the data directory has not been initialized it reports an error directing you to run init. To use a non-standard port, specify --port at init (or configure) time; any subsequent reference to the server, in the Ghidra client or with the bsim command, must then specify that port with the postgresql:// URL (see “Ghidra and BSim URLs”).

The --force option to stop and restart disconnects clients immediately, rolling back any in-progress transactions, rather than waiting for connections to finish.

Running as a systemd Service (Linux): the server can be installed as a persistent systemd service so that it starts automatically at boot, running the postgres process as the data directory owner. Installing and removing the service must be done as root (via sudo), and the server must be stopped when the service is installed:

Once a service is installed, the start, stop, and restart commands are delegated to systemctl and must be run as root; status reports the service installation and running state.

BSim makes use of PostgreSQL security mechanisms to enforce privileges and authenticate users. The bsim_ctl command wraps the subset of functionality described here, but other adjustments are possible by connecting directly to the server and issuing SQL commands.

The PostgreSQL server, as configured for BSim, only accepts connections via SSL, so communications in transit are always encrypted regardless of the authentication settings.

The SSL/TLS server certificate is established at init time and is independent of the client authentication method described below. If a password-protected keystore is supplied with the --keystore option, its CA-signed certificate and private key are installed and the server listens on all interfaces, allowing remote clients to authenticate the server. If no keystore is supplied, a self-signed certificate is generated and the server binds to the loopback interface only; remote access is disabled.

IMPORTANT: Connections to a newly established server will fail unless the server certificate issuer is considered a trusted certificate issuer (.e.g., Certificate Authority (CA)). A local server reached via a localhost name or address is authenticated exactly like any other server by default.

When a self-signed certificate is used by a server, client systems must be configured in one of two ways: 1) add the self-signed server certificate to their set of trusted certificates, or 2) if server is limited to localhost use only local server authentication may be waived by setting the following VM property (see support/launch.properties):

Waive it only where every account on the local machine is trusted. A loopback connection is not by itself proof of the server's identity: a rogue local process which binds the port ahead of the intended server would be accepted in its place, together with any credential the client then sends it (the administrative database password among them). A deployment which cannot accept that should supply a --keystore with a CA-signed certificate instead, which requires no waiver. Remote deployments must always supply one.

Where the server presents a CA-signed certificate from a --keystore, a client authenticates it using the trust established for that client: the operating system trust store and the Java default trust store. A certificate issued by an authority those already contain requires no client configuration at all. For an internal authority which they do not contain, the client has three options:

NOTE: the bsim and bsim_ctl utilities set ghidra.cacerts automatically if the property has not been specified and a file named cacerts is present within a Ghidra installation root directory. Placing such a file there therefore restricts these utilities to the authorities it contains. Both properties are described in support/launch.properties.

PostgreSQL uses the concept of roles to grant access privileges based on particular users. Generally, a user's role is determined by the username used to establish the connection. For BSim, each user role is granted one of two privilege levels: user, which allows read-only access to the server for normal queries, and admin, which additionally allows database creation, ingest, update, and deletion.

BSim supports three different authentication methods, when connecting as a client or during database ingest and maintenance. This method is established for a server by the init command.

The authentication method is established when the data directory is initialized with the init command; starting the server does not change it. If the settings really need to be changed, the configure command can be issued. It takes the same options as the init command and must be run while the server is running, so that the administrator can be authenticated and any credential the new authentication method requires can be established before the change takes effect. The server is left running and the change takes effect when it is next restarted.

Using the configure command on a server with an established set of users will likely require other disruptive changes to create passwords or associate Distinguished Names with users, if they didn't exist before. The administrator's own credential is handled by configure itself: a change to password prompts for a new password if they have none, and a change to pki requires their certificate (the global --cert option) so their identity mapping can be established from it. Every other user must then be given a password with resetpassword, or a Distinguished Name with adduser, once the server is restarted.

If it is determined that only the database administrators have OS level, local, access to the server's host machine, they can choose to use the noLocalAuth option as part of the init or configure commands. This disables authentication for users connecting to the server by the 'localhost' interface. This may facilitate the use of scripts for ingest etc., where working with passwords is cumbersome. Authentication is still enforced for any remote connection.

NOTE: A host whose local accounts are not all trusted should be given a --keystore so that the configured authentication applies to local connections too.

Only local authentication is affected. The --auth mode is still recorded and continues to determine what adduser establishes for each user — a password, or a certificate identity mapping — so those credentials are already in place if configure is later used with a --keystore to enable remote access. Users should therefore continue to be added in accordance with the configured authentication mode, even though local connections are not currently authenticated.

The PostgreSQL administrative role established when the server is initialized (the --user option of bsim_ctl init, defaulting to the invoking user) becomes the administrator for that server. No other username/role is initially known to the server. New usernames/roles can be added to the server using the following command:

If password authentication has been set for the server, the new user's password will initially be set to 'changeme'. If PKI authentication has been set for the server, the Distinguished Name, as bound to the new user's certificate, must be provided when issuing the adduser command, via the --dn option. The Distinguished Name must be presented as a string containing a comma separated sequence of attribute/value pairs that uniquely identifies a certificate.

IMPORTANT: the server matches the entire Distinguished Name, so no attribute may be omitted, and it must be given exactly as the server renders the subject of the user's certificate: in RFC 2253 form (most specific attribute first, no spaces around the separating commas), matching case and spacing. No normalization is performed on either side of the comparison, so specifying it correctly is the administrator's responsibility. For a given certificate the required form is reported by:

The name actually registered is echoed by adduser, and the name registered for every user can be reviewed at any time with the listusers command — which together are the means of confirming a Distinguished Name was entered correctly. A user whose registered name does not match the certificate they present will be unable to connect; re-running adduser for that user replaces it.

NOTE: a server which was initialized by Ghidra 12.1.x or older matches only the Common Name (CN) taken from the Distinguished Name, rather than the whole of it. Such a server keeps doing so, because the entries it already holds for its users were registered that way and cannot be re-derived (each user's certificate is held by that user). adduser follows whichever the server is configured for, so the --dn option is supplied the same way in either case; listusers and status report which is in use.

New users are by default only given user permissions, meaning that they can only place queries to the database and cannot ingest, update, or delete data. The new user can be given admin privileges (by an existing administrator) by issuing the command:

The relevant configuration files are at the top level of the data directory:

Within postgresql.conf, BSim appends two clearly delimited blocks after the standard PostgreSQL defaults:

More generally, any setting outside the managed block - the tunable block, or the standard PostgreSQL defaults above it - may be edited and is preserved across a configure; only the managed block is regenerated. The performance parameters provided in the tunable block are:

The minimum TLS version and cipher suites live in the managed block (currently ssl_min_protocol_version = 'TLSv1.2') and, like the other managed settings, are established by init/configure rather than edited directly.

The pg_hba.conf file is used to configure which connections the server accepts for a particular outward facing IP address and what security mechanisms are enforced for those connections. Currently all addresses are configured to accept SSL connections only, except possibly for 'localhost'. Administrators can currently filter connections based on usernames and the particular database (which corresponds to Ghidra's concept of repository).

The installation-wide default configuration values are held in a serverconfig.xml template (in $(ROOT)/Ghidra/Features/BSim/data), analogous to the Ghidra Server's server.conf. It provides reasonable defaults that differ from the standard PostgreSQL defaults and is read by init (and by configure when it regenerates the managed block). Entries marked tunable="true" (the performance settings) are written to the editable tunable block of a new data directory's postgresql.conf.

There are therefore two ways to adjust the performance settings:

Remote client access to the PostgreSQL server may have network firewalls which must be considered and properly configured to allow network access. Both dedicated network firewalls and OS-level firewalls must be considered.

Firewall configurations are beyond the scope of this document, however for simple single-node installations on Linux the firewall-cmd may be used to allow incoming connections to the appropriate port (TCP port 5432 is the default for PostgreSQL). This does not consider network firewall devices which may also impact connectivity.

NOTE: The above Linux firewall command assumes the firewalld package has been installed on the system.

In order to make use of Elasticsearch with BSim, the database administrator must install the lsh.zip plug-in as part of the Elasticsearch deployment. The plug-in is available in the Ghidra extension named BSimElasticPlugin. The extension may be unzipped to a temporary location or use Ghidra's Install Extensions capability which will unpack it into the users platform-specific config directory indicated in the detail view of the Install Extensions window. The extension is not used directly by Ghidra and is only needed for the lsh.zip elasticsearch plug-in which must be installed on every node of the cluster before a BSim repository can be created. The description below shows how to enable the BSim plug-in for a single node, but this will need to be repeated for any additional nodes.

Refer to the README.md file within the unpacked extension for important plugin details. The plugin file stipulates a specific elasticsearch version and may require an adjustment and repack.

Assuming the add-on has been unpacked, the plug-in can be installed to a single node using the elasticsearch-plugin command in the bin directory of the node's Elasticsearch installation.

Replace the initial portion of the absolute path in the URL to point to the Ghidra installation. Once the plug-in is installed, the toy deployment can be (re)started from the command-line by running

This will dump logging messages to the console, and you should see [lsh] listed among the loaded plug-ins as the node starts up.

The open Elasticsearch distribution starts with password authentication enabled by default. When a node is started up for the first time, as described above, an elastic user is created with a randomly generated password that is reported, once, to the console. For a toy deployment, it may be convenient to add additional users via curl commands. The following example creates a user named ghidrauser with a default password "changeme", using the elastic users credentials. The generated password for the elastic user must be substituted for the XXXXXX at the beginning of the command.

curl -k -u elastic:XXXXXX -X POST "https://localhost:9200/_security/user/ghidrauser?pretty" -H 'Content-Type: application/json' -d'
{
  "password" : "changeme",
  "roles" : [ "viewer" ],
  "full_name" : "Ghidra User",
  "email" : "ghidrauser@example.com"
}
'
	      

Elasticsearch uses the concept of roles to grant access privileges to particular users. The built-in role viewer, as in the example above, can be used to grant users read-only access to a database. The built-in superuser role grants administrator privileges.

Once a user has been created they may change their own password from the BSim client, or from the command line with the bsim changepassword command (see “bsim”).

Assuming an Elasticsearch cluster is running and the plug-in has been properly installed, all other parts of BSim interact transparently with the cluster. The bsim command, described in Ingesting Executables, and the Ghidra/BSim client, described in Querying a BSim Database, require no additional configuration to work with Elasticsearch, except users must provide the correct URL to establish a connection. Elasticsearch communicates over https, and BSim clients automatically assume they are communicating with Elasticsearch when they see this protocol. Alternatively, the protocol may be specified as elastic when using the bsim command. Elasticsearch use by BSim assumes a default port of 9200 unless otherwise specified when specifying the server host. See “Ghidra and BSim URLs” for additional information about URLs.

Remote client access to the Elasticsearch server/cluster may have network firewalls which must be considered and properly configured to allow network access. Both dedicated network firewalls and OS-level firewalls must be considered.

Firewall configurations are beyond the scope of this document, however for simple single-node installations on Linux the firewall-cmd may be used to allow incoming connections to the appropriate port (TCP port 9200 is the default for elasticsearch). This does not consider network firewall devices which may also impact connectivity.

NOTE: The above Linux firewall command assumes the firewalld package has been installed on the system.