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 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.3.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.3.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”.

The basic start-up and shut-down is accomplished with the same command-line script, which takes either the keyword start or stop as the first parameter. The second parameter must be an absolute path to the chosen data directory.

The data directory should already exist and should initially not contain any files. The first time a server is started for a particular data directory, a large number of configuration files and other sub-directories associated with the PostgreSQL server will automatically be created. Upon subsequent restarts the existing configuration will be reused.

The start command can take an optional --port parameter. This can be used to specify a non-standard port for the PostgreSQL server to listen on. In this case, any subsequent reference to the BSim server, in the Ghidra client, or with the bsim command described below, must specify the port. When using the bsim command, a non-default port must be explicitly specified with the BSim postgresql:// URL (see “Ghidra and BSim URLs” for more details).

The stop command can take the keyword force as an optional parameter. Without this, the shutdown of the server will wait until all currently connected clients finish their sessions. Adding this parameter will cause all clients to be disconnected immediately, rolling back any transactions, and the server will shutdown immediately.

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.

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 initial start command.

The authentication method should be established once, the first time the start command is issued for the server on an empty data directory. Subsequent restarts of the server will not change these settings. If the settings really need to be changed, the changeauth command can be issued. It takes the same options as the start command and can only be run if the server is shutdown first.

Using the changeauth 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.

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 start or changeauth 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.

The username used to start the server for the first time, causing the initialization of the data directory, 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 certificated 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. Currently, the Common Name (CN=) is the only attribute inspected by the PostgreSQL server, so other attributes can be omitted.

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:

The most important configuration parameters in postgresql.conf are:

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).

There is a serverconfig.xml which contains a few of the default configuration values that are most crucial for the BSim Database. Beware: This file is currently parsed only once for the entire lifetime of a particular data directory: it is read only when the data directory is first initialized, i.e. the first time the bsim_ctl start command is invoked on the empty directory. This file is intended to provide reasonable defaults that are different from the standard PostgreSQL defaults. To provide site specific configuration, changes should be made to the normal PostgreSQL configuration files.

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 add-on named BSimElasticPlugin, which unpacks into a standard Ghidra installation. The file lsh.zip is a standard Elasticsearch plug-in that 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.

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 up 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.

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.