# Ghidra Server Architecture and Team Collaboration Setup Guide

> Learn the Ghidra Server architecture and set up team collaboration. Utilize RMI and SSL for secure, version-controlled RE projects. Enhance your reverse engineering workflow today.

- Repository: [National Security Agency/ghidra](https://github.com/NationalSecurityAgency/ghidra)
- Tags: architecture
- Published: 2026-03-04

---

**Ghidra Server uses an RMI-based architecture with SSL-protected communication to enable real-time collaboration on reverse engineering projects through version-controlled shared repositories.**

The Ghidra Server is the central collaboration service in the NationalSecurityAgency/ghidra repository that allows multiple analysts to share projects, track file versions, and work simultaneously on binary analysis tasks. Understanding the Ghidra Server architecture is essential for teams needing secure, concurrent access to reverse engineering assets across distributed environments.

## Core Architecture Components

The server follows a modular design where the same binaries function on developer workstations, CI headless nodes, or production servers. Each component handles specific responsibilities within the distributed system.

### Main Entry Point and RMI Registry

The **`GhidraServer`** class serves as the bootstrap mechanism. Located at [`Ghidra/Features/GhidraServer/src/main/java/ghidra/server/remote/GhidraServer.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Features/GhidraServer/src/main/java/ghidra/server/remote/GhidraServer.java), this component starts an RMI registry on a configurable port, instantiates SSL socket factories via `ServerPortFactory.getRMISSLPort()`, and registers a single `GhidraServerHandle` object that clients use for all remote procedure calls.

### Remote Interface and Client Communication

The **`GhidraServerHandle`** interface (implemented by `GhidraServer`) exposes remote methods for repository lookup, authentication, and block-stream creation. Found in [`Ghidra/Framework/Remote/src/main/java/ghidra/framework/remote/GhidraServerHandle.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/Remote/src/main/java/ghidra/framework/remote/GhidraServerHandle.java), this interface funnels all client-side operations through a centralized remote proxy.

### Repository Management

Two classes manage persistent storage:

- **`RepositoryManager`** ([`Ghidra/Features/GhidraServer/src/main/java/ghidra/server/RepositoryManager.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Features/GhidraServer/src/main/java/ghidra/server/RepositoryManager.java)): Manages the set of repositories under the server's root directory, handling creation, deletion, and lookup while enforcing read/write privileges.
- **`Repository`** ([`Ghidra/Features/GhidraServer/src/main/java/ghidra/server/Repository.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Features/GhidraServer/src/main/java/ghidra/server/Repository.java)): Represents a single version-controlled repository on disk, storing data in an **indexed filesystem** (`IndexedLocalFileSystem`) that provides fast random access and automatic index rebuilding.

### Authentication and Security

The **`UserManager`** ([`Ghidra/Features/GhidraServer/src/main/java/ghidra/server/UserManager.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Features/GhidraServer/src/main/java/ghidra/server/UserManager.java)) maintains authorized user lists through password files, Active Directory, PKI, or JAAS modules. Pluggable authentication implementations include:

- `PasswordFileAuthenticationModule` for local password files
- `PKIAuthenticationModule` for certificate-based access
- `JAASAuthenticationModule` for enterprise integration

The entire stack is **SSL-protected by default**, with configurable TLS protocol versions controlled via `TLS_SERVER_PROTOCOLS_PROPERTY` in [`GhidraServer.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/GhidraServer.java).

### High-Performance Data Transfer

The **`BlockStreamServer`** ([`Ghidra/Features/GhidraServer/src/main/java/ghidra/server/stream/BlockStreamServer.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Features/GhidraServer/src/main/java/ghidra/server/stream/BlockStreamServer.java)) provides high-throughput binary streaming for large files such as program binaries and symbol files. Accessed via `RemoteBlockStreamHandle`, this component uses dedicated SSL sockets to keep the regular RMI channel lightweight.

## Communication Flow

The interaction between clients and server follows a strict sequence:

1. **Server Startup**: `GhidraServer.main()` parses command-line options (IP, port, authentication mode), creates the appropriate `AuthenticationModule`, and registers the server in the RMI registry.

2. **Client Connection**: Ghidra UI or headless scripts build a `GhidraURL` object (parsed by [`Ghidra/Framework/Project/src/main/java/ghidra/framework/protocol/ghidra/GhidraURL.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Framework/Project/src/main/java/ghidra/framework/protocol/ghidra/GhidraURL.java)), which contacts the RMI registry, obtains the remote `GhidraServerHandle`, and authenticates via the selected module.

3. **Repository Access**: After authentication, the client requests a `RepositoryHandle`. The server returns a proxy forwarding all filesystem operations to the underlying `Repository` instance.

4. **Data Transfer**: Large binary blobs travel through the `BlockStreamServer` using dedicated SSL sockets, isolating bulk data from control messages.

## Setting Up Ghidra Server for Team Collaboration

### Prepare the Repository Root

Create a dedicated directory for version-controlled projects:

```bash
SERVER_ROOT=/opt/ghidra/server_repo
mkdir -p "$SERVER_ROOT"
chmod 770 "$SERVER_ROOT"

```

The root directory holds one subdirectory per repository. Names are mangled internally (e.g., `My_Project` becomes `_my___project`).

### Configure Authentication

For password-file authentication, generate salted hashes using the Ghidra utility:

```bash
$GHIDRA_HOME/support/create_user.sh admin

```

Append additional users as needed. The password file path is referenced with the `-p` flag during server startup.

### Launch the Server

Start the server with SSL enabled and password authentication:

```bash
java -cp "$GHIDRA_HOME/build/libs/ghidra.jar" \
    ghidra.server.remote.GhidraServer \
    -ip 0.0.0.0 \
    -p /opt/ghidra/server_repo \
    -a0 \
    -jaas none

```

Key command-line options (documented in `GhidraServer.USAGE_ARGS`):

- `-ip <hostname>`: Bind address (`0.0.0.0` for all interfaces)
- `-p <repoPath>`: Root repository directory
- `-a#`: Authentication mode (`0`=password file, `1`=AD/Kerberos, `2`=PKI, `4`=JAAS)
- `-anonymous`: Allow read-only anonymous access
- `-autoProvision`: Create missing users automatically after successful authentication

### Create Shared Repositories

From the Ghidra UI:

1. Select **File → New Project → Shared Project**
2. Choose **Ghidra Server** as the location
3. Enter the server URL: `ghidra://myhost/TeamRepo`
4. Supply credentials when prompted

Programmatically, use the `GhidraServerHandle` API:

```java
import ghidra.framework.remote.GhidraServerHandle;
import ghidra.framework.protocol.ghidra.GhidraURL;

GhidraServerHandle server = GhidraURL.getServerHandle("ghidra://myhost");
server.createRepository("admin", "TeamRepo");

```

### Connect Team Members

Collaborators connect using the standard URL format:

```text
ghidra://myhost/TeamRepo

```

Once authenticated, all changes are version-controlled on the server and immediately visible to other connected users.

## Practical Configuration Examples

### Production Server Startup Script

```bash
#!/bin/bash

# start_ghidra_server.sh

GHIDRA_HOME=/opt/ghidra
REPO_ROOT=/opt/ghidra/server_repo

java -cp "$GHIDRA_HOME/build/libs/ghidra.jar" \
     ghidra.server.remote.GhidraServer \
     -ip 0.0.0.0 \
     -p "$REPO_ROOT" \
     -a0 \
     -jaas none \
     -d mydomain.com \
     -autoProvision \
     -anonymous

```

### Headless Repository Creation

```java
import ghidra.framework.remote.GhidraServerHandle;
import ghidra.framework.protocol.ghidra.GhidraURL;
import ghidra.framework.remote.RepositoryHandle;

public class TeamSetup {
    public static void main(String[] args) throws Exception {
        GhidraServerHandle server = GhidraURL.getServerHandle("ghidra://myhost");
        server.createRepository("admin", "MalwareAnalysis2024");
        
        RepositoryHandle repo = server.getRepository("MalwareAnalysis2024");
        System.out.println("Repository created with handle: " + repo);
    }
}

```

### Accessing Shared Programs

```java
import ghidra.framework.remote.GhidraServerHandle;
import ghidra.framework.remote.RepositoryHandle;
import ghidra.framework.protocol.ghidra.GhidraURL;
import ghidra.program.model.listing.Program;

public class SharedAccess {
    public static void main(String[] args) throws Exception {
        GhidraServerHandle server = GhidraURL.getServerHandle("ghidra://myhost");
        RepositoryHandle repo = server.getRepository("MalwareAnalysis2024");
        Program prog = repo.getProgram("sample.exe", true);
        System.out.println("Loaded program entry point: " + prog.getEntryPoint());
    }
}

```

## Summary

- **Ghidra Server** operates as an RMI-based service with SSL-encrypted communication, defaulting to port 13100.
- The architecture separates concerns between connection handling (`GhidraServer`), repository management (`RepositoryManager`), and authentication (`UserManager`).
- **Indexed filesystems** provide fast random access to version-controlled data stored in the server root directory.
- **Pluggable authentication** supports password files, Active Directory, PKI, and JAAS through command-line flags (`-a0` through `-a4`).
- **Block-stream servers** isolate large file transfers from RMI control channels to maintain responsiveness.
- Administrative tasks can be performed via [`ServerAdmin.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/ServerAdmin.java) for repository migration and diagnostics.

## Frequently Asked Questions

### What network ports does Ghidra Server require?

Ghidra Server defaults to port **13100** for RMI registry communication. The `BlockStreamServer` allocates additional ephemeral ports for SSL data transfer. Configure the primary port using the `-ip` option followed by the port number (e.g., `-ip 0.0.0.0:13100`). Firewall rules must allow outbound connections from clients to these ports on the server host.

### How does Ghidra Server handle user authentication?

The server supports four authentication modes selected via the `-a` flag: password files (`-a0`), Active Directory/Kerberos (`-a1`), PKI certificates (`-a2`), and JAAS (`-a4`). The `UserManager` class enforces password expiration policies and supports anonymous read-only access when the `-anonymous` flag is enabled. For enterprise environments, `PKIAuthenticationModule` or `JAASAuthenticationModule` provides integration with existing identity infrastructure.

### Can Ghidra Server run on Windows Server?

Yes. The Java-based architecture runs on any platform supporting a Java Runtime Environment. Windows deployments should adjust file paths in startup scripts and ensure the repository root directory has appropriate NTFS permissions. Use Windows Service wrappers or scheduled tasks to maintain server persistence, as the `ghidraRun` wrapper and `GhidraServer` class work identically across platforms.

### How do I backup Ghidra Server repositories?

Backup the repository root directory specified by the `-p` flag. Each repository subdirectory contains an `IndexedLocalFileSystem` with data files and index metadata. Use [`ServerAdmin.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/ServerAdmin.java) (located at [`Ghidra/Features/GhidraServer/src/main/java/ghidra/server/ServerAdmin.java`](https://github.com/NationalSecurityAgency/ghidra/blob/main/Ghidra/Features/GhidraServer/src/main/java/ghidra/server/ServerAdmin.java)) to gracefully pause writes during backup windows. The server supports repository migration and integrity checking through command-line admin tools documented in the server's usage output.