diff --git a/Ghidra/RuntimeScripts/Common/server/svrREADME.html b/Ghidra/RuntimeScripts/Common/server/svrREADME.html deleted file mode 100644 index c52b2a72ed..0000000000 --- a/Ghidra/RuntimeScripts/Common/server/svrREADME.html +++ /dev/null @@ -1,1119 +0,0 @@ - - - - - - - -Ghidra Server README - - - -

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

- -

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

- -

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

- -(Back to Top) -
-

Server Logs

- -

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

- -

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

- -(Back to Top) -
-

User Authentication

- -

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

-

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

-

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

- -(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 macOS

- -NOTE: macOS has limited support (see macOS - Service fails to start). - -

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

-
-

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

-

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

- -(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. 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 queing, 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>"]
-
-

- - - -(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/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 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. -
    -
  2. Uninstall an installed Ghidra Server Service by following the Uninstall Service - instructions corresponding to your operating system (Windows - or Linux/macOS).
    3. -
    -
  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. -
    -
  4. Copy the old repositories directory to the new Ghidra Server - installation directory.
    5. -
    -
  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. -
    -
  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/macOS).
    7. -
- -

-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 / Known Issues

- -

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

-
- -

Client/Server connection errors

 -

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

- -
-

MS Windows - ERROR Incorrect function (WindowsWatchService)

 -

-The Ghidra Server employs a file system watcher service for the repositories directory which must -reside within a locally mounted NTFS or ReFS filesystem. -

- -
-

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

- -
-

macOS - Service fails to start (macOS 10.14 Mojave and later)

 -

-The installed service may fail to start with macOS Mojave (10.14) and later due -to changes in the Mac OS 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. -

- -(Back to Top) -
- - - diff --git a/Ghidra/RuntimeScripts/Common/server/svrREADME.md b/Ghidra/RuntimeScripts/Common/server/svrREADME.md new file mode 100644 index 0000000000..bc670b7d65 --- /dev/null +++ b/Ghidra/RuntimeScripts/Common/server/svrREADME.md @@ -0,0 +1,845 @@ +# Ghidra Server README + +## Table of Contents +* [Introduction](#introduction) +* [Java Runtime Environment](#java-runtime-environment) +* [Server Configuration](#server-configuration) +* [Server Logs](#server-logs) +* [Server Memory Considerations](#server-memory-considerations) +* [Note regarding use of DNS (name lookup service)](#note-regarding-use-of-dns-name-lookup-service) +* [User Authentication](#user-authentication) +* [SSH User Authentication](#ssh-user-authentication) +* [Server Options](#server-options) +* [Running Ghidra Server on Microsoft Windows](#running-ghidra-server-on-microsoft-windows) + * [Server Scripts](#server-scripts-located-within-the-server-subdirectory) + * [Running Server in Console Window](#running-server-in-console-window-intended-for-diagnostic-use-only) + * [Install as Automatic Service](#install-as-automatic-service-must-have-administrator-privilege) + * [Uninstall Service](#uninstall-service-must-have-administrator-privilege) +* [Running Ghidra Server on Linux or macOS](#running-ghidra-server-on-linux-or-macos) + * [Server Scripts](#server-scripts-located-within-the-server-subdirectory-1) + * [Running Server in Console Window](#running-server-in-console-window) + * [Install as Automatic Service](#install-as-automatic-service-must-have-admin-privilege) + * [Uninstall Service](#uninstall-service-must-have-admin-privilege) +* [Server Administration](#server-administration) +* [Repository Backup](#repository-backup) +* [Clearing Obsolete Checkouts](#clearing-obsolete-checkouts) +* [PKI Certificates](#pki-certificates) +* [Managing PKI Certificate Authorities](#managing-pki-certificate-authorities) +* [Upgrading the Ghidra Server Installation](#upgrading-the-ghidra-server-installation) +* [Troubleshooting / Known Issues](#troubleshooting--known-issues) + * [Failures Creating Repository Folders / Checking in Files](#failures-creating-repository-folders--checking-in-files) + * [Client/Server connection errors](#clientserver-connection-errors) + * [MS Windows - ERROR Incorrect function (WindowsWatchService)](#ms-windows---error-incorrect-function-windowswatchservice) + * [MS Windows - ERROR Missing Temp Directory](#ms-windows---error-missing-temp-directory) + * [MS Windows 7 and 8 - ghidraSvr.bat, svrInstall.bat, or svrUninstall.bat Error](#ms-windows-7-and-8---ghidrasvrbat-svrinstallbat-or-svruninstallbat-error) + * [Linux - SELinux must be disabled](#linux---selinux-must-be-disabled) + * [Linux - Potential hang from /dev/random depletion](#linux---potential-hang-from-devrandom-depletion) + * [macOS - Service fails to start](#macos---service-fails-to-start-macos-1014-mojave-and-later) + +## 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). + +You may also refer to the _InstallationGuide.html_ file within the _docs/_ subdirectory for general +installation information. + +([Back to Top][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][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. + +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. + +([Back to Top][top]) + +## Server Logs +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. + +([Back to Top][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][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. + +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](#server-options) section for more details. + +([Back to Top][top]) + +## User Authentication +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](#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` 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](#server-administration)). In addition, each user must + configure Ghidra with the location of their signing key/certificate keystore file (see + [PKI Certificates](#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](#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 `` 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.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. + +([Back to Top][top]) + +## Server Options + +### Networking options + +#### `-ip ` +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, relies on a dynamic DNS or other network address translation for incoming connections. +This option establishes the property value for _java.rmi.server.hostname_. + +#### `-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 this option is not specified connections will be accepted on +any interface. + +#### `-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. + +#### `-n` +Enables 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. + +### Authentication options + +#### `-a#` +Allows a user authentication mode to be specified (see [User Authentication](#user-authentication)) + +#### `-d` +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 ` +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. + +#### `-u` +Allows 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. + +#### `-autoProvision` +Enable 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. + +#### `-anonymous` +Enable 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. + +#### `-ssh` +Enable SSH as an alternate form of authentication when using `-a0` authentication mode. + +([Back to Top][top]) + +## Running Ghidra Server on Microsoft Windows + +### Server Scripts (located within the server subdirectory) +* __svrInstall.bat__: Installs server as service (_ghidraSvr_) +* __svrUninstall.bat__: Removes previously installed server service +* __svrAdmin.bat__: Facilitates Ghidra Server administrative commands (see + [Server Administration](#server-administration)) +* __ghidraSvr.bat__: Provides a variety of commands for controlling the server when running as a + daemon process. When running this script it accepts a single argument which is one of the + following commands. Many of these commands are included so that this script may be used for + controlling the service. + * __console__: Starts server within the current terminal window. The _console_ argument may be + omitted to allow for double-click execution in this mode. + * __start__: Starts the previously installed Ghidra Server service + * __stop__: Stops the installed Ghidra Server service which is currently running + * __restart__: Stops and restarts the previously installed Ghidra Server service + * __status__: Displays the current status of the Ghidra Server (_ghidraSvr_) service + +__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. + +### 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 + +__NOTE__: It is very important that you uninstall the service prior to doing any of the following +activities: +* Deleting or upgrading the Ghidra installation +* Moving/renaming the Ghidra installation directory + +([Back to Top][top]) + +## Running Ghidra Server on Linux or macOS + +__NOTE__: macOS has limited support (see +[macOS - Service fails to start](#macos---service-fails-to-start-macos-1014-mojave-and-later)). + +### Server Scripts (located within the server subdirectory) +* __svrInstall__: Installs server as service (_ghidraSvr_ or _wrapper.ghidraSvr_) +* __svrUninstall__: Removes previously installed server service +* __svrAdmin__: Facilitates Ghidra Server administrative commands (see + [Server Administration](#server-administration)) +* __ghidraSvr__: Provides a variety of commands for controlling the server when running as a + daemon process. When running this script it accepts a single argument which is one of the + following commands. Many of these commands are included so that this script may be used for + controlling the service. + * __console__: Starts server within the current terminal window + * __start__: Starts the previously installed Ghidra Server service + * __stop__: Stops the installed Ghidra Server service which is currently running + * __restart__: Stops and restarts the previously installed Ghidra Server service + * __status__: Displays the current status of the Ghidra Server (_ghidraSvr_) service + +### 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 performing an +upgrade to an existing Ghidra Server installation you must uninstall the existing Ghidra Server +first (see [Uninstall Service](#uninstall-service-must-have-admin-privilege)). + +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 ``. +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= +``` +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. + +__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: +* deleting or upgrading the Ghidra installation +* moving/renaming the Ghidra installation directory + +__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. + +([Back to Top][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. 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](#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](#server-logs)). + +The general command usage is: +```bash +svrAdmin [] + [-add [--p]] + [-grant <"+r"|"+w"|"+a"> ] + [-revoke ] + [-remove ] + [-reset [--p]] + [-dn ""] + [-list [...]] + [-list [--users]] + [-users] + [-migrate-all] + [-migrate ""] +``` + +#### `` +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](#server-options). Alternatively, the initial password may be specified by including +the optional `--p` parameter which will prompt for an initial password. + +Examples: +```bash +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: +```bash +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: +```bash +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: +```bash +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: +```bash +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: +```bash +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: +```bash +svrAdmin -list +svrAdmin -list --users +svrAdmin -list mySID +``` + +#### `-users` (List All Users) +Lists all users with server access. + +Example: +```bash +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: +```bash +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: +```bash +svrAdmin -migrate "myProject" +``` + +([Back to Top][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][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: + +```bash +find -name checkout.dat -exec rm {} \; +``` + +where `` 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 +`` and the other parameters. If you specify the incorrect `` or omit the +correct `-name` argument, you may remove important files without the ability to recover. + +([Back to Top][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](#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][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/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](#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. + +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: + +```bash +keytool -printcert -v -file +``` +where: +* `` 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 your cacerts file. + +The following command should be used to add a CA certificate to a new or existing cacerts file: + +```bash + keytool -import -alias "" -file -storetype jks -keystore +``` +where: +* `` is the name of the CA corresponding to the imported certificate. +* `` is the file containing the Base64 encoded CA certificate to be imported. +* `` 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_ 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][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](#uninstall-service-must-have-administrator-privilege) or + [Linux/macOS](#uninstall-service-must-have-admin-privilege)). + +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/`). 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](#install-as-automatic-service-must-have-administrator-privilege) or + [Linux/macOS](#install-as-automatic-service-must-have-admin-privilege)). + +__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](#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][top]) + +## Troubleshooting / Known Issues + +### 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. + +### Client/Server connection errors +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 +``` + +### MS Windows - ERROR Incorrect function (WindowsWatchService) +The Ghidra Server employs a file system watcher service for the repositories directory which must +reside within a locally mounted NTFS or ReFS filesystem. + +### 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_. + +### macOS - Service fails to start (macOS 10.14 Mojave and later) +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. + +([Back to Top][top]) + +[top]: #ghidra-server-readme \ No newline at end of file diff --git a/Ghidra/RuntimeScripts/certification.manifest b/Ghidra/RuntimeScripts/certification.manifest index 9831b1ceec..c50f377991 100644 --- a/Ghidra/RuntimeScripts/certification.manifest +++ b/Ghidra/RuntimeScripts/certification.manifest @@ -4,7 +4,7 @@ ##MODULE IP: Public Domain Common/server/jaas.conf||GHIDRA||||END| Common/server/server.conf||GHIDRA||||END| -Common/server/svrREADME.html||GHIDRA||||END| +Common/server/svrREADME.md||GHIDRA||||END| Common/support/GhidraGo/ghidraGoREADME.html||GHIDRA||||END| Common/support/analyzeHeadlessREADME.md||GHIDRA||||END| Common/support/buildGhidraJarREADME.txt||GHIDRA||||END|