Ghidra Server

Multi-user collaborative reverse engineering server

Overview

The Ghidra Server enables multi-user collaborative reverse engineering by providing centralized repository management, version control, and concurrent access to Ghidra projects. It utilizes the YAJSW Java service wrapper and provides OS-specific scripts for running as a system service.

Only a single server instance should run against any given repositories directory. Running concurrent instances may lead to data corruption.

Architecture

The Ghidra Server is incorporated into the standard Ghidra distribution:

• Unpack Ghidra distribution
• Configure server settings
• Perform OS-specific installation
• Start the service

# Server directory structure
Ghidra/
├── server/
│   ├── server.conf       # Main configuration
│   ├── ghidraSvr         # Service control script
│   ├── svrInstall        # Installation script
│   ├── svrUninstall      # Removal script  
│   └── svrAdmin          # Administration tool

Server Configuration

Editing server.conf

Before installation, modify server/server.conf to configure:

1. Repositories Directory

   Specify an absolute path outside the Ghidra installation:

   wrapper.app.parameter.1=-d
   wrapper.app.parameter.2=/data/ghidra-repos
   
2. Authentication Mode

   Choose your authentication method (see User Authentication)

3. Network Settings

   Configure IP addresses and ports if needed

4. Memory Allocation

   Adjust wrapper.java.maxmemory based on your repository size

Use a repositories directory on locally attached storage for best performance. The server requires filesystem watcher support which may not work on remotely-mounted filesystems.

Memory Considerations

The server maintains in-memory state for all repositories. Calculate memory requirements:

# Formula:
maxmemory = 16 + (32 * FileCount/10000) + (2 * ClientCount)

# Example: 100,000 files and 25 clients
maxmemory = 16 + (32 * 100000/10000) + (2 * 25) = 386

# Recommended setting (double the calculated value):
wrapper.java.maxmemory=772

There are no safeguards when insufficient memory is available. Out of memory errors can cause severe server failure.

User Authentication

Ghidra Server supports multiple authentication modes:

Authentication Modes

No Authentication

Any added user can connect without password.

# No special configuration needed
# Not recommended for production

Local Password (-a0)

Passwords maintained in users file within repositories directory.

wrapper.app.parameter.3=-a0

• Default password: changeme
• Must be changed within 24 hours (configurable via -e option)

Active Directory (-a1)

Kerberos authentication against Active Directory.

wrapper.app.parameter.3=-a1
wrapper.app.parameter.4=-dmydomain.com

PKI Certificates (-a2)

Authentication using PKI user certificates.

wrapper.app.parameter.3=-a2
wrapper.app.parameter.4=-ghidra.cacerts=/path/to/cacerts

Each user’s distinguished name (DN) must be associated with their User ID.

JAAS (-a4)

Java Authentication and Authorization Service.

wrapper.app.parameter.3=-a4
wrapper.app.parameter.4=-jaas
wrapper.app.parameter.5=jaas.conf

Supports LDAP, PAM, external programs, and more.

SSH Authentication

When using -a0 mode with -ssh option, headless analyzers can authenticate via SSH keys:

# Generate SSH key pair (PEM format required)
ssh-keygen -m pem -t rsa -b 2048

# Copy public key to server
cp id_rsa.pub repositories/~ssh/<username>.pub

Ghidra Server does not support OpenSSH key format or ecdsa/ed25519 key types. Use RSA with PEM format.

Server Options

Networking Options

-ip · hostname

Remote access hostname or IPv4 address for client connections

-i · IP address

Bind server to specific IPv4 interface

-p · port · default: "13100"

Base TCP port (server uses 3 consecutive ports)

-n · flag

Enable reverse DNS lookup for IP addresses when logging

Authentication Options

-a · number

Authentication mode: 0 (password), 1 (AD), 2 (PKI), 4 (JAAS)

-d · domain

Active Directory domain name (e.g., -dmydomain.com)

-e · days · default: "1"

Password expiration days (0 = no expiration)

-u · flag

Allow specifying user ID at login time

-autoProvision · flag

Auto-create users on successful authentication (AD and JAAS only)

-anonymous · flag

Enable anonymous read-only access to designated repositories

Installation and Management

Windows Installation

1. Install Service

   Run svrInstall.bat with Administrator privileges

   cd server
   svrInstall.bat
   
2. Start Service

   Use Service Control Panel or:

   ghidraSvr.bat start
   
3. Verify Status

   ghidraSvr.bat status
   

Console Mode (Diagnostic)

ghidraSvr.bat console
# Press Ctrl-C to stop

Linux/macOS Installation

1. Set Java Home (Recommended)

   Edit ghidraSvr script before installation:

   GHIDRA_JAVA_HOME=/usr/lib/jvm/java-21-openjdk
   
2. Install Service

   sudo ./svrInstall
   
3. Start Service

   sudo ./ghidraSvr start
   

Use a major-version symbolic link for Java path to survive Java updates:

GHIDRA_JAVA_HOME=/usr/lib/jvm/java-21-openjdk  # Good
GHIDRA_JAVA_HOME=/usr/lib/jvm/java-21.0.1-openjdk  # Avoid

Service Commands

Command	Description
start	Start the Ghidra Server service
stop	Stop the running service
restart	Stop and restart the service
status	Display current service status
console	Run in foreground (diagnostic mode)

Server Administration

The svrAdmin script manages users and repositories:

User Management

Add User

svrAdmin -add <username>
svrAdmin -add <username> --p  # Prompt for password

Remove User

svrAdmin -remove <username>

Reset Password

svrAdmin -reset <username>
svrAdmin -reset <username> --p  # Set new password

Set PKI DN

svrAdmin -dn <username> "CN=Name,OU=Org,O=Company,C=US"

Repository Access

Grant Access

# READ_ONLY access
svrAdmin -grant <username> +r <repository>

# WRITE access  
svrAdmin -grant <username> +w <repository>

# ADMIN access
svrAdmin -grant <username> +a <repository>

Repository Migration

Migrate from Mangled to Indexed filesystem storage:

# Migrate all repositories
svrAdmin -migrate-all

# Migrate specific repository
svrAdmin -migrate "MyRepository"

Migration to Indexed filesystem is one-way. Backup repositories before proceeding.

Server Logs

The server produces two log files:

Log File	Location	Purpose
wrapper.log	Ghidra installation root	Service wrapper output
server.log	Repositories directory	Server application log

In console mode, wrapper.log output is directed to the terminal.

Repository Backup

1. Stop Server

   # Linux/macOS
   sudo ./ghidraSvr stop
   
   # Windows  
   ghidraSvr.bat stop
   
2. Backup Directory

   tar -czf ghidra-repos-backup.tar.gz /data/ghidra-repos/
   
3. Restart Server

   # Linux/macOS
   sudo ./ghidraSvr start
   
   # Windows
   ghidraSvr.bat start  
   

While backups can be taken while the server is idle, it’s safest to stop the server during backup operations.

Clearing Obsolete Checkouts

Admins can clear checkouts via Ghidra client or command line:

# Stop server first
sudo ./ghidraSvr stop

# Clear all checkouts in repository
find /data/ghidra-repos/MyRepo -name checkout.dat -exec rm {} \;

# Clear all checkouts on entire server
find /data/ghidra-repos -name checkout.dat -exec rm {} \;

# Restart server
sudo ./ghidraSvr start

Be extremely careful with the find command. Incorrect parameters can delete important files.

PKI Certificates

Server Certificate Configuration

Edit server.conf to specify server keystore:

wrapper.app.parameter.10=-ghidra.keystore=/path/to/server.p12
wrapper.app.parameter.11=-ghidra.password=keystorePassword

Managing Certificate Authorities

The cacerts file can be in PEM or JKS format:

Inspect Certificate (PEM)

keytool -printcert -v -file certificate.crt

CA certificates in PEM format should have an extra blank line after each END CERTIFICATE line when concatenating.

Upgrading Server

1. Backup

   Backup repositories and configuration files

2. Uninstall Old Service

   cd old-ghidra/server
   sudo ./svrUninstall
   
3. Extract New Version

   Unzip new Ghidra distribution to new directory

4. Migrate Configuration

   Copy wrapper.app.parameter.* lines from old to new server.conf

   Do NOT copy entire server.conf file
5. Copy Repositories

   If not using external directory, copy repositories to new installation

6. Install New Service

   cd new-ghidra/server  
   sudo ./svrInstall
   sudo ./ghidraSvr start
   

Troubleshooting

Common Issues

Connection Errors

Symptom: non-JRMP server at remote endpoint

Cause: Incompatible Ghidra client version

Solution: Ensure client and server versions are compatible

Windows Watch Service Error

Symptom: ERROR Incorrect function (WindowsWatchService)

Cause: Repositories not on NTFS/ReFS filesystem

Solution: Move repositories to locally-mounted NTFS or ReFS volume

Missing Temp Directory (Windows)

Symptom: Server fails to start as service

Solution: Add to server.conf:

wrapper.java.additional.3=-Djava.io.tmpdir=C:\Windows\Temp

Linux SELinux

Symptom: Server won’t start on Linux

Solution: Disable SELinux in /etc/selinux/config

/dev/random Depletion (Linux)

Symptom: SSL/PKI operations hang

Solution: Install haveged daemon:

sudo apt-get install haveged
sudo systemctl enable haveged

DNS Configuration

Both server and clients make extensive use of forward and reverse DNS lookups. Improperly configured DNS can cause severe performance delays.

The server publishes a remote access address and listens on interfaces:

• Published Address: What clients use to connect (configurable via -ip)
• Listening Address: Which network interfaces accept connections (configurable via -i)

Source Code References

# Main implementation  
~/workspace/source/Ghidra/Features/GhidraServer/

# Server scripts
Ghidra/RuntimeScripts/Common/server/

# Documentation
Ghidra/RuntimeScripts/Common/server/svrREADME.md

Next Steps

Version Tracking

Use server for collaborative version tracking sessions

BSim

Store BSim databases on server for team access