Ghidra Server README

Table of Contents

Introduction

The Ghidra Server is incorporated into the standard Ghidra software distribution. Simply unpack the Ghidra distribution, configure the Ghidra Server and perform the OS-specific install and you should have the server running in no time.

The Ghidra Server utilizes the YAJSW Java service wrapper to launch the application and provides OS specific scripts which enable the application to run as a service.

NOTE: It is very important that only a single server instance is running against any given server repositories directory. This can be assured if only the default port is ever used. The daemon/service mechanism assumes that only one instance of the service exists. Attempting to run a second concurrent instance may lead to difficulties and is not supported.

NOTE: It is highly recommended that the installation files for Ghidra reside on a local drive and that the intended Ghidra Server process owner is granted full access to the Ghidra installation directory (this is frequently not the case for NFS/SMB mounted home directories).

NOTE: It is highly recommended that you establish a repositories directory outside of your Ghidra installation directory so that it may be re-used more easily with future upgraded installations of Ghidra.

You may also refer to the InstallationGuide.html file within the docs subdirectory for general installation information.

(Back to Top)

Java Runtime Environment

The installation of a suitable Java Runtime Environment must be completed before installing or running the Ghidra Server. Please refer to the Ghidra Installation Guide to identify a suitable version. Since the Ghidra Server is unable to interactively identify a Java installation at runtime it must rely upon the setting of JAVA_HOME, execution search PATH or the use of standard Java installation locations. It is important to consider the service execution environment which may differ from the administrator who may be installing the service. For this reason use of an installed Java release may be preferable over one that is simply unpacked to an arbitrary location.

(Back to Top)

Server Configuration

Before installing and running the Ghidra Server, the server/server.conf file must be modified to suit your particular needs. Within this file, locate the lines labeled: 

    wrapper.app.parameter.#
These lines correspond to a sequential list of server command line arguments - be sure not duplicate a parameter number. The comments within this file indicate the available command line arguments which should be specified here based upon the desired user authentication, repositories directory location and other associated options.

You should generally avoid using the default repositories location and specify a location outside your installation directory using an absolute path specification.

When upgrading your Ghidra installation, you will need to copy your app parameters from your old server.conf to the new server.conf. Do not copy the entire server.conf file as this may prevent the server from running properly. If running as a service, you must run the server/svrUninstall script from the old installation before running the server/svrInstall script from the new installation. Using a non-default repositories directory outside your Ghidra installation will simplify the migration process.

(Back to Top)

Server Memory Considerations

The Ghidra Server currently maintains an in-memory state for all repositories. We are aware that this can limit the scalability of the Ghidra Server. The maximum memory used by the process can be set within the server/server.conf file by adjusting the following setting: 

    wrapper.java.maxmemory

WARNING! There are currently no safeguards when insufficient memory is available to the Ghidra Server and can cause severe failure if an out of memory error occurs.

The following formula can be used to approximate an appropriate setting for this maxmemory value where FileCount represents the maximum number of repository files and ClientCount is the number of active Ghidra clients connected at one time. 

    wrapper.java.maxmemory = 16 + (32 * FileCount/10000) + (2 * ClientCount)
Example: 
    100,000 files and 25 connected Ghidra clients
    16 + (32 * 100000/10000) + (2 * 25) = 386
    wrapper.java.maxmemory=772    (2 * 386, see NOTE below)

NOTE: Due to the dynamic memory demands on the server not considered by this calculation (e.g., open file handles, etc.), the actual maxmemory setting used should be larger than the calculated value. At a minimum, it is recommended that the calculated value be doubled, and a larger value may be appropriate based upon server loading.

The Java VisualVM tool (if available for your host) may also be used to examine memory usage while the server is running. This tool is NOT provided with any Ghidra distribution.

(Back to Top)

Note regarding use of DNS (name lookup service)

Both Ghidra Server and client application make extensive use of forward and reverse network name lookups. If this service is not properly configured on your network and hosts, names may fail to be resolved or in certain cases cause severe performance delays due to improperly serviced DNS name/address queries.

It is also highly recommended that the server's local hostname (with and with domain name) be mapped to its IP address with the hosts file (/etc/hosts on Linux). If this is not desirable for your setup, then the server should be explicitly bound to a specific IP address (see the -ip parameter in the Server Options section).

(Back to Top)

User Authentication

The Ghidra Server has been designed to support many possible user authentication modes:

  1. No authentication - any user which has been added to the server may connect without password or credentials.

  2. Local Ghidra password (-a0) - passwords associated with each user added to the server are maintained in the users file located within the repositories directory. The user will be prompted for this password when connecting to the server. The default password changeme is used when a user is first added or when the user is reset (see Server Administration). This default password must be changed by the user to avoid its expiration.

  3. PKI authentication (-a2) - user authentication is performed using PKI user certificates. When using this mode, the distinguished name (DN) for each user must be associated with each server User ID (see Server Administration). In addition, each user must configure Ghidra with the location of their signing key/certificate keystore file (see PKI Certificates for more information).

    4. Please note that each user's certificate must be issued by a trusted certificate authority which has been properly added to the Ghidra Server's cacerts file. See Managing PKI Certificate Authorities for more information.

    In an attempt to simplify the determination of user DN's, a log file (UnknownDN.log) records user DNs which are unknown. After adding a user to the server, ask the user to attempt a login using their PKCS certificate. This should result in their DN being recorded to this log file. The server administrator may now copy the appropriate DN from this log file when assigning the DN for a user.
  4. Use of an SSH pre-shared key (-ssh) is supported as an alternate form of authentication when using Local Ghidra password (-a0). This SSH authentication is currently supported by the Headless Analyzer only. See SSH User Authentication for configuration details.

(Back to Top)

SSH User Authentication

When the -ssh option has been included in conjunction with password based authentications mode (-a0 a user's SSH public key may be added to the server to facilitate access by a Headless Analyzer. An SSH public key file must be added to the server repository for each user who requires headless SSH authentication. The SSH public key file (e.g., id_rsa.pub) must be copied to the repositories/~ssh subdirectory to a file named <username>.pub. Removing the file will eliminate SSH based authentication for the corresponding user. When creating the ~ssh subdirectory, it should be owned by the Ghidra Server process owner with full access and any SSH public keys readable by the process owner. Changes to the SSH public key files may be made without restarting the Ghidra Server.

(Back to Top)

Server Options

(Back to Top)

Running Ghidra Server on Microsoft Windows

Server Scripts (located within the server subdirectory)

Running Server in Console Window (intended for diagnostic use only)

NOTE: Starting the server in console mode is generally intended for diagnostic use only. Extreme care must be taken to ensure that any user who starts the Ghidra Server via this script has full access to all directories and files within the root repository directory.

If the Ghidra Server is not already running, it may be started within a console window by running the ghidraSvr.bat console command. When you wish to terminate the server, use the Ctrl-C key sequence within the server console window and wait for a clean shutdown.


Install as Automatic Service (must have Administrator privilege)

The Ghidra Server may be installed as an automatic service by executing the svrInstall.bat script. This script may be run from a CMD window, or by double-clicking the script file from an Explorer window. Once installed, the server will start automatically when the system is booted. Immediately after running this script the service will not be running, you will need to either reboot or start the service from the Service Control Panel.


Uninstall Service (must have Administrator privilege)

If after installing the Ghidra Server as a service you wish to uninstall it, you may run the svrUninstall.bat script. You must stop the service via the Service Control Panel prior to running this script. This script may be run from a CMD window, or by double-clicking the script file from an Explorer window.

NOTE: It is very important that you uninstall the service prior to doing any of the following activities:

(Back to Top)

Running Ghidra Server on Linux or Mac-OSX

Server Scripts (located within the server subdirectory)

Running Server in Console Window

NOTE: Starting the server in console mode is generally intended for diagnostic use only. Care must be taken to ensure that any user who starts the Ghidra Server via this script has full access to all directories and files within the root repository directory.

If the Ghidra Server is not already running, it may be started within a terminal window by running the command: ghidraSvr console. When you wish to terminate the server, use the Ctrl-C key sequence within the server console window and wait for a clean shutdown.


Install as Automatic Service (must have admin privilege)

The Ghidra Server may be installed as an automatic service by executing the svrInstall script. Once installed, the server will start automatically when the system is booted.

If it is preferred to run the service with a dedicated local user account, the following entry may be added to the server.conf file with the appropriate account specified in place of <uid>. A dedicated local service account should generally be a no-login account with a corresponding group identifier with the same name (i.e., see /etc/passwd and /etc/group). The local account should be established and specified with server.conf prior to installation of the Ghidra Server service. 

	wrapper.app.account=<uid>

It is also important that the repositories directory and Ghidra installation files be owned by the service account with proper permissions. Note that while the Ghidra Server Java process will run using the specified uid the wrapper process will continue to run as root and monitor/manage the Java process.


Uninstall Service (must have admin privilege)

If after installing the Ghidra Server as a service you wish to uninstall it, you may run the svrUninstall script.

NOTE: It is very important that you uninstall the service prior to doing any of the following activities:

(Back to Top)

Server Administration

The script svrAdmin, or svrAdmin.bat, provides the ability to manage Ghidra Server users and repositories. This script must be run from a command shell so that the proper command line arguments may be specified.

The general command usage is: 

    svrAdmin [<server-root-path>]
             [-add <user_sid>] 
             [-remove <user_sid>] 
             [-reset <user_sid>] 
             [-dn <user_sid> "<user_dn>"]
             [-admin <user_sid> "<repository_name>"]
             [-list]
             [-users]
             [-migrate-all]
             [-migrate "<repository_name>"]

(Back to Top)

Repository Backup

As with any server, it is highly recommended that your server repositories directory be periodically backed-up or whenever an upgrade (or data migration) is performed. While backups may be taken while the Ghidra Server is idle (e.g., after midnight), it is always safest to stop the Ghidra Server while a backup is in progress.

(Back to Top)

Clearing Obsolete Checkouts

Any user who has Admin privilege of a specific repository may use the Ghidra client to View Checkouts for a specific file and Delete individual checkouts from those that are listed. The View Checkouts action is available from the popup-menu of the Ghidra Project Window by right-clicking on a specific project file.

Under special circumstances (e.g., classroom environment) it may be desirable to remove all checkouts either for a specific repository or an entire Ghidra Server. Under Linux/Mac this is most easily accomplished from the command shell while the Ghidra Server is stopped. The following command may be used: 

    find <repo-path> -name checkout.dat -exec rm {} \;
where <repo-path> is the directory path of a specific named repository root, or the parent repositories directory if clearing checkouts for all repositories.

WARNING! Since the find command is recursive, care must be taken when specifying the <repo-path> and the other parameters. If you specify the incorrect <repo-path> or omit the correct -name argument, you may remove important files without the ability to recover.

(Back to Top)

PKI Certificates

PKI keys/certificates can be used to authenticate clients and/or servers. When using the Ghidra Server PKI authentication mode this corresponds to "client authentication" which requires the server.conf to specify a cacerts file location and each user client to configure a user signing key/certificate keystore file. If clients wish to authenticate the server, the server.conf must specify a server key/certificate keystore file and each user client must configure a cacerts file. See Managing PKI Certificate Authorities for more information on configuring a cacerts file.

User and server certificates must be acquired through one of many trusted authorities identified by the cacerts file installed by the peer system. Your network support staff should be able to help you acquire a suitable signing key/certificate in the form of either a *.p12, *.pks, or *.pfx file.

User's of the Ghidra GUI application can install their key/certificate file via the project window menu item Edit->Set PKI Certificate.... The user will be prompted for their keystore password the first time key access is required for a network connection after starting the application. If using the analyzeHeadless script, see the analyzeHeadlessREADME.html file for details.

If the Ghidra Server will be installing a server certificate, the server.conf file should be modified to properly identify the server's key/certificate location (ghidra.keystore) and password (ghidra.password).

(Back to Top)

Managing PKI Certificate Authorities

When utilizing PKI authentication for a Ghidra Server a set of certificates for trusted Certificate Authorities (CA) must be collected and added to a cacerts keystore file created using the Java keytool. The Java keytool can be found within the Java Development Kit (JDK) provided with Ghidra (java/bin/keytool) or any other Java distribution. The default cacerts keystore file location is Ghidra/cacerts and is also specified by the ghidra.cacerts property setting within the server.conf file. Uncomment this specification within the server.conf file to activate use of the cacerts for all incoming SSL connections (i.e., all Ghidra client users must install and employ the use of their personal PKI signing certificate for both headed and headless use - see PKI Certificates). Clients can also impose server authentication for all HTTPS and Ghidra Server connections by creating the cacerts file and enabling the ghidra.cacerts property setting within the support/launch.sh and/or launch.bat scripts.

Individual CA public key certificates should be obtained in a Base64 encoding (see sample below). If pasting the encoded certificate into a file, be sure to include an extra blank line after the END CERTIFICATE line.

Sample Base64 encoded certificate: 

-----BEGIN CERTIFICATE-----
laSKCIElkjsudCUDusjSUkjeMSUjAJHDuLQWMCMausALkKXMXOOjSKSUjssjSKAA
ksDSDjLKJHAuemCXXUmxxqjaskuDSYRmxiqgDlakkUSUdhemjASKUakjhuEhxMSD
...
ksJKDwocQwyeEIcbzHtyrSLfoeyGCmvbNLGHpgoruSTYQafzDFTgwjkJHCXVDjdg
KDowiyYTXkcuiwCJXuyqCHpdoORriwwcCWUskucuwHDJskuejdkUWJCUDSjujsUE
-----END CERTIFICATE-----

You can inspect the contents of a Base64 encoded certificate file with the following command: 

    keytool -printcert -v -file <base64file>
where: The Owner common name (CN) displayed by this command should be used as the alias when importing the certificate into your cacerts file.

The following command should be used to add a CA certificate to a new or existing cacerts file: 
    keytool -import -alias "<caAlias>" -file <base64file> -storetype jks -keystore <cacerts-file>
where: The keystore password will be requested and is used to restrict future modifications to the cacerts file.

When starting the Ghidra Server with PKI authentication enabled, the CA certificates contained within the cacerts file will be dumped to the log with their expiration dates.

Please note that the Ghidra Server does not currently support Certificate Revocation Lists (CRLs).

(Back to Top)

Upgrading the Ghidra Server Installation

  1. Be sure to backup your projects and tools to ensure that the new Ghidra installation does not overwrite any of your data. Individual program files upgraded to a newer version of Ghidra can not be opened with an older version.

  2. Uninstall an installed Ghidra Server Service by following the Uninstall Service instructions corresponding to your operating system (Windows or Linux/Mac-OSX).

  3. Unzip the new Ghidra distribution to a new installation directory (general unpacking and installation guidelines may be found in ghidra_x.x/docs/InstallationGuide.html).

  4. Copy the old repositories directory to the new Ghidra Server installation directory.

  5. Copy the wrapper.app.parameter.# lines from your old server/server.conf file to the new installation server/server.conf. For 5.0 release and earlier, your old server.conf file is located within a platform-specific directory (core/os/<platform>). No other changes should be made to your new server.conf file.

    Do not replace the new server.conf file with your old server.conf file, as this could cause server problems.

  6. If desired, install the Ghidra Server Service from the new installation server subdirectory by following the instructions corresponding to your operating system (Windows or Linux/Mac-OSX).

WARNING! As of Ghidra 7.0 a new project/server storage implementation, Indexed-V1, has been added which is not compatible with older versions of Ghidra. The Indexed-V0 filesystem storage allows longer filenames and paths to exist within a project, while the V1 version expands support to facilitate some of the very large project/repository features introduced in Ghidra 7.0. Since the legacy storage implementation (Mangled) used by older projects and repositories is still supported, conflicting storage behavior may exist between a Ghidra project and its server repository for long filename/path support. It is highly recommended that all server repositories and associated projects be migrated to the new Indexed storage implementation in a coordinated fashion after making a complete backup. All new Ghidra projects will utilize the new Indexed storage implementation, so care should taken when creating shared projects with older repositories.

NOTE: If using Ghidra 6.0.x, opening a project which uses the newer Indexed-V1 filesystem may cause the project storage to revert to the older Indexed-V0 filesystem.

A user may determine which storage implementation is used by a project by viewing the Project Info display (via Project -> View Project Info...). Local projects using the legacy Mangled filesystem may be migrated to the new Indexed filesystem via this Project Info panel. The status of Ghidra Server repositories storage can be determined and flagged for migration via the server/svrAdmin script (described in the Server Administration section). Please note that any migration to the Indexed filesystem storage is a one-way conversion so a backup of your project or server repositories directory is highly recommended before proceeding.

(Back to Top)

Troubleshooting

Failures Creating Repository Folders / Checking in Files

If you see continuous failures to create repository folders or failures to check in files, check the disk space on the server or folder permissions. When the server runs out of disk space, it cannot create folders or check in files.


MS Windows - ERROR Missing Temp Directory

Running the Ghidra Server as an installed service under Windows may attempt to use a non-existing temporary directory (e.g., C:\Windows\system32\config\systemprofile\AppData\Local\Temp\). The work-around for this is to configure the server to use an existing temporary directory (e.g., C:\Windows\Temp). This can be done by editing the server.conf file, locate the wrapper.java.additional entries and add/uncomment an entry with your temporary directory specified. For example: 

    wrapper.java.additional.3=-Djava.io.tmpdir=C:\Windows\Temp
Be sure to use the next unique sequence number for your wrapper.java.additional entry.


MS Windows 7 and 8 - ghidraSvr.bat, svrInstall.bat, or svrUninstall.bat Error

The following error may occur when attempting to install/uninstall/start/stop/restart the Ghidra Server under MS Windows 7 or 8 even if the user is a member of the Administrator group: 

    Access denied: please check the user credentials
The user executing these scripts must be a member of the Administrator group and must be run with elevated privilege. The best way to accomplish this is to run the CMD shell using the Run as Administrator action which is available by right-clicking on a command shortcut or batch file. If the CMD shell is run in this manner, the Ghidra Server scripts may then be executed within the shell to run with administrator privilege. Failure to run the scripts in this manner may cause failure information to be hidden from view due to the privilege escalation mechanism.


Linux - SELinux must be disabled

The Ghidra Server may not start properly if SELinux has not been disabled. This setting is specified in the file /etc/selinux/config.


Linux - Potential hang from /dev/random depletion

SSL communications and the PKI/SSH authentication mechanisms employed by GHIDRA make use of the Java SecureRandom class to generate random numbers required by various cryptographic techniques. On Linux systems this class makes use of /dev/random to produce these random numbers which in turn relies on other system entropy sources to feed it. We have seen that /dev/random can become depleted which can cause the dependent Java application to hang. While Java claims to have settings which should allow /dev/urandom to be used, these security settings do not appear to work as intended. The best workaround we have found for systems which exhibit this problem is to install haveged (HArdware Volatile Entropy Gathering and Expansion Daemon) which will satisfy the entropy demand needed by /dev/random.

(Back to Top)