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: All Ghidra Server deployments should have a server certificate generated by a recognized
Certificate Authority (CA) and established via the ghidra.keystore property. If a keystore is
not specified, the server will operate with a self-signed certificate and only listen for
connections on the server's loopback/localhost interface. An auto-generated self-signed certificate
will not pass client-side validation, so such a deployment requires each client to waive server
authentication for loopback connections by specifying the client VM property
-Dghidra.disable.loopback.server.authentication=true (see support/launch.properties). Waive it
only where every local account on the client machine is trusted, since a loopback connection is not
by itself proof of the server's identity. See
Server Certificate and Client CA Certificates
for more details.
You may also refer to the GettingStarted.html file within the Ghidra installation root directory for general installation information.
The installation of a suitable Java Runtime Environment must be completed before installing or
running the Ghidra Server. Please refer to the Getting Started document 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.
Ghidra client/server communications rely on a cryptographically secure interface that relies on proper configuration. The framework that facilitates this is frequently referred to as Public Key Infrastructure (PKI).
All server deployments should preferably have a server certificate generated by a recognized
Certificate Authority (CA) to allow client systems to properly validate server connections.
This also requires each client system to properly maintain a complete set of trusted Certificate
Authorities (CA) which facilitate server authentication. Use of a self-signed certificate
should generally be avoided since they would need to be added individually as a trusted certificate
by each user. How trusted certificates are managed by each client user/system varies by
Operating System (OS).
The Ghidra Server relies on properly configured CA Certificate trust stores when PKI Authentication is enabled (-a2) to facilitate client-authentication. Additionally, client applications always rely on CA certificates when communicating with a secure server (SSL) to facilitate server-authentication. There are a variety of trust store configuration mechanisms that Ghidra will use for its default SSL Context:
Application Trust Store - Ghidra allows an application trust store to be specified via the
ghidra.cacerts VM property. In the case of the Ghidra Server this property can be specified within
the server.conf file and is required when PKI Authentication mode (-a2) is used. This property
may also be specified for a Ghidra client applications which may be specified within the
support/launch.properties file. When this property is specified all other trust stores below are
ignored.
OS Trust Store - Each operating system has adopted a unique approach for managing CA certificates. MS Windows and macOS provide a convenient User Certificate Manager GUI, while the support for this with Linux varies greatly based upon specific Linux release. This trust store will be included when an Application Trust Store has not been specified and will be merged with the Default Trust Store provided with Java.
On Unix systems, which lack a User Certificate Manager, the Java property ghidra.unix.default.cacerts
may specify another directory which may contain individual trusted certificates. These will be
used in addition to those defined by the system.
Default Trust Store - Each installation of Java includes a set of standard commercial CA Certificates within a default trust store. This trust store will be included when an Application Trust Store has not been specified.
When configuring any server it is highly recommended that a properly signed server certificate be obtained from a suitable Certificate Authority (CA) so that a connecting client may properly authenticate the server using a properly configured CA. For large organizational servers this is very important. It is also possible to generate a self-signed certificate and keystore when installing for a closed internal network where trust is more tightly controlled. In such cases, the self-signed server certificate may be added by clients as a trusted certificate.
The certTool utility included with Ghidra may be used to generate a certificate request and/or
a PKCS#12 key store (see PKI Management Tools below).
At its core, PKI is the framework of roles, policies, hardware, software, and procedures needed to create, manage, distribute, use, store, and revoke digital certificates and manage public-key encryption.
Think of PKI as the digital identity and trust ecosystem for the Internet. Here is a quick breakdown of its main purpose:
The Problem: On an open network (like the Internet), how do you know a web-site, server, or user is actually who they claim to be?
The PKI Solution: PKI establishes trust by using a trusted third party (i.e., Certificate Authority (CA) ) to vouch for identities. The CA signs a digital certificate (binding an identity to a public key), allowing secure, encrypted communication (using the keys and certificates detailed in the syllabus above).
To make this trust work, PKI relies on three main elements:
Confidentiality : Encrypting data so that only the intended recipient (the holder of the matching private key) can read it.
Authentication : Proving identity. For example: when you connect to https://github.com,
PKI verifies that you are actually talking to that server, not an imposter.
Integrity : Ensuring that data cannot be quietly altered in transit. If a hacker tampers with a signed message or certificate, the digital signature becomes invalid.
Private Key : A secret cryptographic key known only to its owner. It is used to generate digital signatures and decrypt data encrypted with the corresponding public key. Must always be kept secure.
Public Key : A non-secret cryptographic key made available to everyone. It is mathematically linked to the private key and used to encrypt data or verify digital signatures.
Certificate : (End-Entity / Leaf): A digital document that binds a public key to an identity (like a domain name or organization). It is digitally signed by a trusted authority to prove authenticity. An individual certificate (with or without its full chain) may be stored with a PEM or DER (*.pem, *.crt, *.cer) file. The PEM format is text based making it the easiest to identify with its '-----BEGIN CERTIFICATE-----' line. Multiple PEM certificate entries may exist in the same file when CA certificates and chains are included.
CA Certificate : A certificate belonging to a Certificate Authority (CA). It is used to sign other certificates. A Root CA signs itself, while an Intermediate CA is signed by a higher authority.
Certificate Chain (Chain of Trust) : A list of certificates starting from the end-entity
certificate, going through one or more intermediate CA certificates, and ending at a trusted
root CA certificate. It allows a client to verify that the end certificate is trustworthy.
Individually stored certificate chains may be stored as concatenation of PEM entries within a
file (*.pem, *.crt, .cer) or as a PKCS#7 file (.p7b, *.p7c).
Key Usage : A certificate extension that defines the specific cryptographic operations the keys can perform (e.g., Digital Signature, Key Encipherment, Client Authentication, Server Authentication).
Key Store : A storage mechanism (i.e., password protected) that can securely store certificate chains, public keys and private keys. When used to store a private key it should only store that key and its corresponding certificate chain. If only storing certificates (e.g., CA certificates), multiple certificates may be stored. Common store file types include PKCS#12 (.p12, .pfx) and Java Key Store (.jks).
*.pem (PEM, Certificates): Text-based format starting with -----BEGIN.... Can hold
certificates, private keys, or chains.
.crt,.cer (PEM or DER, Certificates): Primarily used to store individual certificates or CA certificates.
*.key (PEM or DER, Private Keys): Typically holds a standalone private key.
*.der (DER, Certificate/Keys): Raw binary encoding of a certificate or key.
*.p12 (PKCS#12, Certificate/Keys): PKCS#12 Key Store. A password-protected archive that bundles a private key, its public key, and the entire certificate chain together.
*.jks (JKS, Certificate/Keys): JKS Key Store. A proprietary Java-specific format used to store certificates and keys for Java applications (though modern Java prefers PKCS#12).
*.csr (PEM or DER, Certificate Signing Request): A file sent to a CA to apply for a certificate. Contains your public key and identity info.
.p7b,.p7c (PKCS#7, CA Certificate Chain): A non-encypted binary-encoded file containing a complete CA certificate chain.
CertTool : Convenience utility provided with Ghidra (server/certTool, server\certTool.bat)
which facilitates Certificate Request generation (include Private Key generation, *.key) and
subsequent PKCS#12 Key Store (*.p12) generation. Also provided is the ability to generate a
private key and self-signed certificate as a PKCS#12 Key Store (*.p12). During certificate
generation the user will be prompted for Distinguished Name properties (DN). The only required
entry is the Command Name (CN) and a protection password.
IMPORTANT! When generating a certificate request or self-signed certificate the user will be prompted to provide Distinguished Name (DN) attributes including a Common Name (CN) which is required. Other DN attributes may be left blank. The user will also be prompted to specify a comma-separated list of Subject Alternative Names (SANs) which is very important. All server hostnames and address forms used to connect to the server must be specified. A client connection to an IP Address or hostname not included in the SAN list may prevent a client from properly validating a server connection.
Allowed Subject Alternative Name (SAN) Forms
Fully Qualified Domain Name (FQDN): myhost.mycompany.com
Simple hostname: myhost
IPv4 Address : 1.2.3.4
NOTE: SAN entries with a wildcard or subnet mask are not currently supported.
CertTool Usage: certTool <command> [options]
Generate Certificate Request
Generate a new private key and a corresponding certificate request (CSR) using supplied Distinguished Name (DN) data supplied via prompts as well as a list of subject alternative names. The CSR in PEM format will be displayed to the console with the intention that it be submitted to a CA for generation of a CA-signed certificate. Once the signed-certificate has been obtained the command below may be used to generate the combined certficate/key key store.
certTool request -outkey <key-file-filename>
Generate Keystore from Signed Certificate and Private Key
Generate a PKCS#12 (*.p12) key store from a private key and signed-certificate w/ CA chain.
If the returned certificate does not include the full CA chain, a separate CA chain should be obtained (e.g., *.p7b file). This chain may correspond to the CA chain only or the full issued certificate chain.
certTool pkcs12 -inkey <key-filename> -cert <cert-filename> [-cachain <cachain-file>] -out <keystore-filename>
Generate Self-Signed Certificate and Keystore
Generate a self-signed certificate (.crt) and keystore (.p12) using supplied Distinguished Name (DN) data supplied via prompts as well as a list of subject alternative names.
NOTE: Use of a self-signed certificate has severe limitations with regard to it being
trusted by a client system. A client system/user will need to add the server's certificate
to their managed OS trusted certificates (Windows or macOS) or to Ghidra's cacerts file
for the client application (see ghidra.cacerts property within support/launch.properties).
Be aware that specifying the ghidra.cacerts property causes that file to be used
exclusively: the OS and Java default trust stores are then ignored. Every certificate
authority the client relies upon must therefore be present within that file, not only the
server certificate being added. Adding the certificate to the OS trust store instead avoids
this, since the OS trust store remains in use when ghidra.cacerts is not specified.
On Unix, where updating the system trust store requires root access, the
ghidra.unix.default.cacerts property offers a third option which may not: it names an
additional file or directory of trusted certificates which is added to the OS trust store as it is
built, rather than replacing it. It applies to Unix only (not Windows or macOS), and is ignored
when ghidra.cacerts has been specified, since the OS trust store is not loaded in that case.
Both properties are described in support/launch.properties for clients and in server.conf for
the server (which itself acts as a client when authenticating an LDAP server for JAAS
authentication).
certTool pkcs12 -self-signed -out <keystore/cert-filename>
OpenSSL : The definitive open-source command-line toolkit for working with X.509 certificates, CSRs, and cryptographic keys. This tool has a very extensive set of commands for performing many cryptographic functions. Searching online for examples of specific use is your best bet at using it.
Example command use: Inspecting a PEM certificate
openssl x509 -in certificate.crt -text -noout
Keytool : A key and certificate management utility built into the Java Development Kit (JDK).
Example command use: Listing contents of a Java keystore
keytool -list -v -keystore keystore.jks
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.
It is highly recommended that you specify a repositories directory outside of your Ghidra installation directory with an absolute path so that it may be re-used more easily with future upgraded installations of Ghidra. Due to the use of a filesystem watcher service the use of a locally attached storage device is preferred and will also ensure the best performance.
NOTE: The server may fail to start if the repository native filesystem does not support the use
of a filesystem watcher service. This could occur if attempting to use a remotely-mounted
filesystem which may lack the required event support. The watcher service is used in conjunction
with command processing associated with the svrAdmin command. If a running server fails to
process queued svrAdmin command requests, the repository native filesystem may be the cause.
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.
The Ghidra Server produces two log files, which for the most part have the same content. The service wrapper.log file generally resides within the Ghidra installation root directory, while the server.log file resides within the configured repositories/ directory. When running the server in console mode all wrapper.log output is directed to the console.
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.
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.
By default the server will attempt to identify an appropriate remote access IPv4 address which will
be written to the log at startup. In addition, the server will listen for incoming connections on
all IPv4 interfaces by default. It is important to understand the difference between the published
remote access address and the listening address (i.e. interface) which are both configurable. See
the -ip and -i options in the Server Options section for more details.
The Ghidra Server has been designed to support many possible user authentication modes:
No authentication: Any user which has been added to the server may connect without password or credentials.
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.
Active Directory via Kerberos (-a1): User authentication is performed against your local
Active Directory system using Kerberos to do so. The -d<ad_domain> argument is required to
specify the domain name of your Active Directory system.
It is also possible to authenticate against your Active Directory system using LDAP. See the LDAP example when using JAAS -a4 mode.
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).
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.
JAAS - Java Authentication and Authorization Service (-a4): User authentication is delegated
to the JAAS subsystem. The -jaas <config_file> argument is required to specify the JAAS config
file. The JAAS config file supplied (server/jaas.conf) contains various example configurations
which may be used to establish an 'auth' configuration section. None of the example
configurations use the 'auth' name so they will be ignored by default.
JAAS is architected similar to Linux/Unix PAM, where a named authentication configuration is possibly composed of several different modules. Ghidra's support of JAAS only handles single simple JAAS modules that requests the name and password from the user.
Some known JAAS login modules:
com.sun.security.auth.module.LdapLoginModule: Allows authentication to an LDAP server. There is an example of using this module to authenticate against an Active Directory system in the jaas.conf file.
net.sf.jpam.jaas.JpamLoginModule (Linux/Unix server only): Allows authentication against the local PAM configuration. You will need to download JPAM from SourceForce and install the libraries in the necessary locations. See the example in the jaas.conf file.
ghidra.server.security.loginmodule.ExternalProgramLoginModule: Spawns an external program for each authentication request, and uses the external program's exit code as the indicator of successful authentication.
There is an example (and non-useful) implementation of an external authenticator provided with the Ghidra installation called server/jaas_external_program.example.sh.
This login module strives to be compatible with Apache's mod_authnz_external API, and you should be able to use any mod_authnz_external authenticator with Ghidra.
The external program is fed the username\n and password\n on its STDIN (i.e., two text lines). The external authenticator needs to exit with 0 (zero) error level if the authentication was successful, or a non-zero error level if not successful.
com.sun.security.auth.module.Krb5LoginModule: Not recommended. This login module is used in
the -a1 Active Directory via Kerberos authentication mode, and as such you should use it that
way.
Use of an SSH pre-shared key (-ssh</): 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.
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.
Each user may generate a suitable SSH key pair with the ssh-keygen command issued from a shell
prompt. A PEM formatted RSA key-pair should be generated using the following command options:
ssh-keygen -m pem -t rsa -b 2048
NOTE: Ghidra Server authentication does not currently support the OPENSSH key format which may
be the default ssh-keygen format (-m option) on some systems such as Ubuntu. In addition, other
key types (-t option) such as ecdsa and ed25519 are not currently supported.
-ip <hostname>Identifies the remote access hostname (FQDN) or IPv4 address which should be used by remote clients to access the server. By default the host name reported by the operating system is resolved to an IPv4 address, if this fails the local loopback address is used. The server log will indicate the remote access hostname at startup. This option may be required when a server has multiple IP interfaces, running within a docker container, or relies on a dynamic DNS or other network address translation for incoming connections. This option establishes the property value for java.rmi.server.hostname. This name should be reflected in the server certificate ('ghidra.keystore' property). Additional host names or IP address used to access the server should also be included within the server's certificate (i.e., subject alternative names).
The -ip option will be ignored if the 'ghidra.keystore' property has been omitted.
-i <#.#.#.#>Forces the server to be bound to a specific IPv4 interface on the server. If specified and the -ip
option is not, the address specified by -i will establish the remote access IP address as well as
restrict the listening interface.
If the 'ghidra.keystore' property (server certificate keystore) has been omitted, only a loopback interface may optionally be specified, otherwise the server will listen on the default 127.0.0.1 loopback interface. If the 'ghidra.keystore' property has been specified, the server will listen on all interfaces unless this option is specified.
-p#Allows the base TCP port to be specified (default: 13100). The server utilizes three (3) TCP ports starting with the specified base port (e.g., 13100, 13101 and 13102). The ports utilized are logged by the server during startup.
-nEnables reverse name lookup for IP addresses when logging (requires proper configuration of reverse lookup by your DNS server). Please note that logging of host names is now disabled by default due to the slow-down which occurs when reverse DNS is not properly configured on the network.
-a#Allows a user authentication mode to be specified (see User Authentication)
-d<ad_domain>Sets the Active Directory domain name. Example: "-dmydomain.com"
-e#Allows the reset password expiration to be set to a specified number of days (default is 1-day). A value of 0 prevents expiration.
-jaas <config_file>Specifies the path to the JAAS config file (when using -a4), relative to the ghidra/server
directory (if not absolute).
See jaas.conf for examples and suggestions. It is the system administrator's responsibility to
craft their own JAAS configuration directive when using the -a4 mode.
-uAllows the server login user ID to be specified at time of login for -a0 authentication mode.
Without this option, the users client-side login ID will be assumed.
-autoProvisionEnable the auto-creation of new Ghidra Server users when they successfully authenticate to the
server (-a1 and -a4 modes only). Users removed from the authentication provider (e.g., Active
Directory) will need to be deleted manually from the Ghidra Server using svrAdmin command.
-anonymousEnable anonymous access support for Ghidra Server and its repositories. Only those repositories which specifically enable anonymous access will be accessible as read-only to an anonymous user.
-sshEnable SSH as an alternate form of authentication when using -a0 authentication mode.
NOTE: The above scripts may be run from a CMD window, or by double-clicking the script file from an Explorer window. Other than the console and status operation, elevated privilege is needed to run these commands. As such the user executing these scripts must be a member of the Administrator group and must be run with elevated privilege. If using Windows Vista or newer, 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.
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.
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.
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
NOTE: It is very important that you uninstall the service prior to doing any of the following activities:
NOTE: macOS has limited support (see macOS - Service fails to start).
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.
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 performing an upgrade to an existing Ghidra Server installation you must uninstall the existing Ghidra Server first (see Uninstall Service).
In order for the installed service script to survive Java system updates, which may change the
installed Java version, it is highly recommended that the GHIDRA_JAVA_HOME variable be set
properly at the top of the ghidraSvr script prior to the server install. GHIDRA_JAVA_HOME should
refer to a non-changing path where Java is installed. For a system-installed Java the major-version
symblic-link path should be specified in favor of a full-version path which stipulates minor-version
information. In addition, it is important that the Ghidra Server service be restarted anytime the
installed Java version is updated where this symbolic link has been modified to reference a newly
installed Java version. Failure to use this approach may result in the Ghidra Server service script
referring to an invalid Java path following an update.
Example setting of GHIDRA_JAVA_HOME within ghidraSvr script:
GHIDRA_JAVA_HOME=/usr/lib/jvm/java-21-openjdk
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.
If after installing the Ghidra Server as a service you wish to uninstall it, you may run the svrUninstall script.
IMPORTANT: It is very important that you uninstall the Ghidra Server service using the original Ghidra software installation. Use of a newer Ghidra software install may not properly uninstall a different service version. This is particularly true if uninstalling a Ghidra Server version prior to 11.2. Such an uninstall will be required when:
NOTE: The service control mechanism for Linux changed with the Ghidra 11.2 release. The init.d mechanism was previously used in all cases, whereas the systemd service mechanism may now used based upon YAJSW preference.
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. This command should only be used after the corresponding Ghidra installation has been properly configured via modification of the server/server.conf file (see Server Configuration) and installed and/or started.
Many of the commands are queued for subsequent execution by the Ghidra Server process. Due to this queuing, there may be a delay between the invocation of a svrAdmin command and its desired affect. The Ghidra log file(s) may be examined for feedback on queued command execution (see Server Logs).
The general command usage is:
svrAdmin [<server-root-path>]
[-add <user_sid> [--p]]
[-grant <user_sid> <"+r"|"+w"|"+a"> <repository_name>]
[-revoke <user_sid> <repository_name>]
[-remove <user_sid>]
[-reset <user_sid> [--p]]
[-dn <user_sid> "<user_dn>"]
[-list <user_sid> [<user_sid>...]]
[-list [--users]]
[-users]
[-migrate-all]
[-migrate "<repository_name>"]
<server-root-path>There is normally no need to specify this argument on the command line.The default server-root-path
is determined by the server.conf setting of the ghidra.repositories.dir variable. This allows
both the server execution and svrAdmin script to utilize the same setting.
-add (Adding a User)All authentication modes require that a user first be added to the server for a connection to be
permitted. If Ghidra password authentication is used (-a0), the initial password is set to
"changeme". This password must be changed by the user within 24-hours to avoid its expiration
(password expiration period can be extended as a server option, see -e
server option. Alternatively, the initial password may be specified by including
the optional --p parameter which will prompt for an initial password.
Examples:
svrAdmin -add mySID
svrAdmin -add mySID --p
-grant (Grant Repository Access for User)Grant access for a specified user and repository where both must be known to the server. Repository access permission must be specified as +r for READ_ONLY, +w for WRITE or +a for ADMIN.
Examples:
svrAdmin -grant mySID +a myRepo
svrAdmin -grant mySID +w myRepo
-revoke (Revoke Repository Access for User)Revoke the access for a specified user and named repository. Currently, revoking access for a user does not disconnect them if currently connected.
Examples:
svrAdmin -revoke mySID myRepo
-remove (Removing a User)A user may be removed from the Ghidra Server and all repositories with this command form. This will only prevent the specified user from connecting to the server in the future and will have no effect on the state or history of repository files. If a repository admin wishes to clear a user's checkouts, this is a separate task which may be performed from an admin's Ghidra client. Currently, removing a user does not disconnect them if currently connected.
Example:
svrAdmin -remove mySID
-reset (Reset User's Ghidra Password)If a user's password has expired, or has simply been forgotten, the password may be reset to
"changeme". After resetting, this password must be changed by the user within 24-hours to avoid
its expiration (password expiration period can be extended as a server option). Alternatively, the
new password may be specified by including the optional --p parameter which will prompt for an
initial password.
Example:
svrAdmin -reset mySID
svrAdmin -reset mySID --p
-dn (Assign User's Distinguished Name)The use of PKI authentication requires that each user's DN be associated with their user SID.
Example:
svrAdmin -dn mySID "CN=MyName,OU=AGENCY,OU=DoD,O=U.S. Government,C=US"
NOTE: After having been added to the server, a user's DN may be copied from the UnknownDN.log file following an attempted connection with their PKCS certificate.
-list (List All Repositories and/or User Permissions)If the --users option is also present, the complete user access list will be included for each
repository. Otherwise, command may be followed by one or user SIDs (separated by a space) which will
limit the displayed repository list and access permissions to those users specified.
Example:
svrAdmin -list
svrAdmin -list --users
svrAdmin -list mySID
-users (List All Users)Lists all users with server access.
Example:
svrAdmin -users
-migrate-all (Migrate All Repositories to Use Indexed File-System Storage)For all repositories which are using the deprecated Mangled Filesystem storage, they will be
marked for migration to the Indexed Filesystem storage with support for longer file pathnames.
The actual migration will be performed when the Ghidra Server is restarted.
Please note that any migration to the Indexed filesystem storage is a one-way conversion so a backup of your server repositories directory is highly recommended before proceeding.
Example:
svrAdmin -migrate-all
-migrate (Migrate a Specified Repository to use Indexed File-System Storage)The specified repository will be marked for migration to the Indexed Filesystem storage with support for longer file pathnames. The actual migration will be performed when the Ghidra Server is restarted.
Please note that any migration to the Indexed filesystem storage is a one-way conversion so a backup of your server repositories directory is highly recommended before proceeding.
Example:
svrAdmin -migrate "myProject"
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.
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/macOS 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.
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).
The Ghidra cacerts file may be used in either PEM or JKS format.
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. The collection of CA
certificates can be used in the form of a PEM Base64 encoded text format (e.g., *.crt, *.cer, *.pem)
or as Java keystore file (JKS, *.jks). The collection of CA certificates within a PEM file
(a.k.a., Apache Certification Authority Bundle) is a simple concatenation of Base64 encoded entries
such as the following sample. If concatenating encoded certificate into a PEM file, be sure to
include an extra blank line after each END CERTIFICATE line.
-----BEGIN CERTIFICATE-----
laSKCIElkjsudCUDusjSUkjeMSUjAJHDuLQWMCMausALkKXMXOOjSKSUjssjSKAA
ksDSDjLKJHAuemCXXUmxxqjaskuDSYRmxiqgDlakkUSUdhemjASKUakjhuEhxMSD
...
ksJKDwocQwyeEIcbzHtyrSLfoeyGCmvbNLGHpgoruSTYQafzDFTgwjkJHCXVDjdg
KDowiyYTXkcuiwCJXuyqCHpdoORriwwcCWUskucuwHDJskuejdkUWJCUDSjujsUE
-----END CERTIFICATE-----
Within a password protected JKS file each CA certificate must be identified with an alias name and
added one at a time using the Java keytool command. The Java keytool can be found within the
Java Development Kit (JDK).
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/TLS 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 support/launch.bat scripts; however, this would require the
Ghidra Server to use a properly signed PKI server certificate and key (See ...).
You can inspect the contents of a Base64 encoded PEM certificate file with the following command:
keytool -printcert -v -file <base64file>
where:
<base64file> is the file containing the Base64 encoded CA certificate to be imported.The Owner common name (CN) displayed by this command should be used as the alias when importing the certificate into a JKS cacerts file.
The following command should be used to add a CA certificate to a new or existing cacerts file.
Only one CA cert is added with each invocation as specified by the CN/alias.
keytool -import -alias "<caAlias>" -file <base64file> -storetype jks -keystore <cacerts-file>
where:
<caAlias> is the name of the CA corresponding to the imported certificate.<base64file> is the file containing the Base64 encoded CA certificate to be imported.<cacerts-file> is the cacerts file to be used by the Ghidra Server (and/or client if needed).The keystore password will be requested and is used to restrict future modifications to the cacerts JKS file. The following command may be used to print all the certificates contained within a JKS file:
keytool -list -v -keystore <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).
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.
Uninstall an installed Ghidra Server Service by following the Uninstall Service instructions corresponding to your operating system (Windows or Linux/macOS).
Unzip the new Ghidra distribution to a new installation directory (general unpacking and installation guidelines may be found in ghidra_x.x/GettingStarted.html).
Copy the old repositories directory to the new Ghidra Server installation directory.
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.
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/macOS).
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.
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.
The Ghidra Server has transitioned to using SSL/TLS connections when accessing the server's RMI registry. This change in communication protocol can cause unexpected symptoms when attempting to connect incompatible versions of Ghidra. When an older incompatible Ghidra client attempts to access a newer SSL/TLS enabled Ghidra Server registry, the following connection error will occur:
non-JRMP server at remote endpoint
The Ghidra Server employs a file system watcher service for the repositories directory which must reside within a locally mounted NTFS or ReFS filesystem.
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.
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.
The Ghidra Server may not start properly if SELinux has not been disabled. This setting is specified in the file /etc/selinux/config.
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.
The installed service may fail to start with macOS Mojave (10.14) and later due to changes in the macOS system protection feature. When the service fails to start it does not provide any error or logging to help determine the cause. Although granting Full Disk Access to Java can be a workaround, this is rather drastic and is not considered desirable since it will allow any Java application to run as root. For this reason, installation of the Ghidra Server as a service on macOS is discouraged.