1024 lines
51 KiB
HTML
1024 lines
51 KiB
HTML
<!DOCTYPE doctype PUBLIC "-//W3C//DTD HTML 4.0 Frameset//EN">
|
|
|
|
<!-- This custom style allows for wrapping within text in /pre/ tags -->
|
|
<style>
|
|
pre {
|
|
white-space: pre-wrap; /* CSS 3 */
|
|
white-space: -moz-pre-wrap; /* Mozilla, since 1999 */
|
|
white-space: -pre-wrap; /* Opera 4-6 */
|
|
white-space: -o-pre-wrap; /* Opera 7 */
|
|
word-wrap: break-word; /* Internet Explorer 5.5+ */
|
|
font-family: 'Courier New', 'Courier';
|
|
font-size: medium;
|
|
}
|
|
|
|
typewriter {
|
|
font-family: 'Courier New', 'Courier';
|
|
}
|
|
</style>
|
|
|
|
<html>
|
|
<head>
|
|
<title>Ghidra Server README</title>
|
|
</head>
|
|
<body>
|
|
|
|
<h1 align="center">Ghidra Server README</h1>
|
|
|
|
<h2>Table of Contents</h2>
|
|
<UL>
|
|
<LI><a href="#introduction">Introduction</a></LI>
|
|
<LI><a href="#javaRuntime">Java Runtime Environment</a></LI>
|
|
<LI><a href="#serverConfig">Server Configuration</a></LI>
|
|
<LI><a href="#serverMemory">Server Memory Considerations</a></LI>
|
|
<LI><a href="#dnsNote">Note regarding use of DNS (name lookup service)</a></LI>
|
|
<LI><a href="#userAuthentication">User Authentication</a></LI>
|
|
<LI><a href="#sshAuthentication">SSH User Authentication</a></LI>
|
|
<LI><a href="#serverOptions">Server Options</a></LI>
|
|
<LI><a href="#running_windows">Running Ghidra Server on Microsoft Windows</a></LI>
|
|
<UL>
|
|
<LI><a href="#windows_scripts">Server Scripts</a></LI>
|
|
<LI><a href="#windows_console">Running Server in Console Window</a></LI>
|
|
<LI><a href="#windows_install">Install as Automatic Service</a></LI>
|
|
<LI><a href="#windows_uninstall">Uninstall Service</a></LI>
|
|
</UL>
|
|
<LI><a href="#running_linux_mac">Running Ghidra Server on Linux or Mac-OSX</a></LI>
|
|
<UL>
|
|
<LI><a href="#linux_mac_scripts">Server Scripts</a></LI>
|
|
<LI><a href="#linux_mac_console">Running Server in Console Window</a></LI>
|
|
<LI><a href="#linux_mac_install">Install as Automatic Service</a></LI>
|
|
<LI><a href="#linux_mac_uninstall">Uninstall Service</a></LI>
|
|
</UL>
|
|
<LI><a href="#serverAdministration">Server Administration</a></LI>
|
|
<LI><a href="#repositoryBackup">Repository Backup</a></LI>
|
|
<LI><a href="#obsoleteCheckouts">Clearing Obsolete Checkouts</a></LI>
|
|
<LI><a href="#pkiCertificates">PKI Certificates</a></LI>
|
|
<LI><a href="#pkiCertificateAuthorities">Managing PKI Certificate Authorities</a></LI>
|
|
<LI><a href="#upgradeServer">Upgrading the Ghidra Server Installation</a></LI>
|
|
<LI><a href="#troubleshooting">Troubleshooting</a></LI>
|
|
<UL>
|
|
<LI><a href="#checkinFailures">Failures Creating Repository Folders / Checking in Files</a></LI>
|
|
<LI><a href="#connectErrors">Client/Server connection errors</a></LI>
|
|
<LI><a href="#windowsMissingTempDirectory">MS Windows - ERROR Missing Temp Directory</a></LI>
|
|
<LI><a href="#windows7and8_scriptErrors">MS Windows 7 and 8 - ghidraSvr.bat, svrInstall.bat,
|
|
or svrUninstall.bat Error</a></LI>
|
|
<LI><a href="#selinuxDisabled">Linux - SELinux must be disabled</a></LI>
|
|
<LI><a href="#randomHang">Linux - Potential hang from /dev/random depletion</a></LI>
|
|
</UL>
|
|
</UL>
|
|
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
|
|
<h2><a name="introduction">Introduction</a></h2>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<P>
|
|
<b>NOTE</b>: 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.
|
|
</P>
|
|
|
|
<P>
|
|
<b>NOTE</b>: 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).
|
|
</P>
|
|
|
|
<P>
|
|
<b>NOTE</b>: It is highly recommended that you establish a repositories directory outside of your
|
|
Ghidra installation directory so that it may be re-used more easily with future upgraded
|
|
installations of Ghidra.
|
|
</P>
|
|
|
|
<P>
|
|
You may also refer to the <typewriter>InstallationGuide.html</typewriter> file within the
|
|
<typewriter>docs</typewriter> subdirectory for general installation information.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="javaRuntime">Java Runtime Environment</a></h2>
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="serverConfig">Server Configuration</a></h2>
|
|
<P>
|
|
Before installing and running the Ghidra Server, the <typewriter>server/server.conf</typewriter>
|
|
file must be modified to suit your particular needs. Within this file, locate the lines labeled:
|
|
<PRE>
|
|
wrapper.app.parameter.#
|
|
</PRE>
|
|
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.
|
|
</P>
|
|
|
|
<P>
|
|
You should generally avoid using the default repositories location and specify a location outside
|
|
your installation directory using an absolute path specification.
|
|
</P>
|
|
|
|
<P>
|
|
When upgrading your Ghidra installation, you will need to copy your app parameters from your old
|
|
<typewriter>server.conf</typewriter> to the new <typewriter>server.conf</typewriter>. Do not copy
|
|
the entire <typewriter>server.conf</typewriter> file as this may prevent the server from running
|
|
properly. If running as a service, you must run the <typewriter>server/svrUninstall</typewriter> script
|
|
from the old installation before running the <typewriter>server/svrInstall</typewriter> script from the
|
|
new installation. Using a non-default repositories directory outside your Ghidra installation
|
|
will simplify the migration process.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="serverMemory">Server Memory Considerations</a></h2>
|
|
|
|
<P>
|
|
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 <typewriter>server/server.conf</typewriter> file by adjusting the following setting:
|
|
<PRE>
|
|
wrapper.java.maxmemory
|
|
</PRE>
|
|
</P>
|
|
|
|
<P>
|
|
<b>WARNING</b>! 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.
|
|
</P>
|
|
|
|
<P>
|
|
The following formula can be used to approximate an appropriate setting for this
|
|
<typewriter>maxmemory</typewriter> value where <typewriter>FileCount</typewriter>
|
|
represents the maximum number of repository files and <typewriter>ClientCount</typewriter>
|
|
is the number of active Ghidra clients connected at one time.
|
|
<PRE>
|
|
wrapper.java.maxmemory = 16 + (32 * FileCount/10000) + (2 * ClientCount)
|
|
</PRE>
|
|
Example:
|
|
<PRE>
|
|
100,000 files and 25 connected Ghidra clients
|
|
16 + (32 * 100000/10000) + (2 * 25) = 386
|
|
wrapper.java.maxmemory=772 <i>(2 * 386, see NOTE below)</i>
|
|
</PRE>
|
|
</P>
|
|
<P>
|
|
NOTE: Due to the dynamic memory demands on the server not considered by this calculation (e.g., open file handles, etc.),
|
|
the actual <i>maxmemory</i> 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.</P>
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="dnsNote">Note regarding use of DNS (name lookup service)</a></h2>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<P>
|
|
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 <typewriter>-ip</typewriter> and <typewriter>-i</typewriter> options in
|
|
the <a href="#serverOptions">Server Options</a> section for more details.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="userAuthentication">User Authentication</a></h2>
|
|
|
|
<P>
|
|
The Ghidra Server has been designed to support many possible user authentication modes:
|
|
|
|
<UL>
|
|
<LI><u>No authentication</u> - any user which has been added to the server may connect without
|
|
password or credentials.</LI>
|
|
<br>
|
|
<LI><u>Local Ghidra password (<typewriter>-a0</typewriter>)</u> - passwords associated with
|
|
each user added to the server are maintained in the <typewriter>users</typewriter> file located
|
|
within the repositories directory. The user will be prompted for this password when connecting
|
|
to the server. The default password <typewriter>changeme</typewriter> is used when a user is
|
|
first added or when the user is reset (see <a href="#serverAdministration">Server
|
|
Administration</a>). This default password must be changed by the user to avoid its expiration.</LI>
|
|
<br>
|
|
<LI><u>Active Directory via Kerberos (<typewriter>-a1</typewriter>)</u> - user authentication is
|
|
performed against your local Active Directory system using Kerberos to do so. The -d<ad_domain>
|
|
argument is required to specify the domain name of your Active Directory system.
|
|
<p>
|
|
It is also possible to authenticate against your Active Directory system using LDAP. See the
|
|
LDAP example when using JAAS -a4 mode.
|
|
</LI>
|
|
<br>
|
|
<LI><u>PKI authentication (<typewriter>-a2</typewriter>)</u> - 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 <a href="#serverAdministration">Server
|
|
Administration</a>). In addition, each user must configure Ghidra with the location of their
|
|
signing key/certificate keystore file (see <a href="#pkiCertificates">PKI Certificates</a>
|
|
for more information).
|
|
<p>
|
|
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 <typewriter>cacerts</typewriter> file. See
|
|
<a href="#pkiCertificateAuthorities">Managing PKI Certificate Authorities</a> for more information.
|
|
<p>
|
|
In an attempt to simplify the determination of user DN's, a log file
|
|
(<typewriter>UnknownDN.log</typewriter>) 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.
|
|
</LI>
|
|
<br>
|
|
<LI><u>JAAS - Java Authentication and Authorization Service (<typewriter>-a4</typewriter>)</u> -
|
|
user authentication is delegated to the JAAS subsystem. The -jaas <config_file> argument
|
|
is required to specify the JAAS config file. The JAAS config file supplied (<i>server/jaas.conf</i>)
|
|
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.
|
|
<p>
|
|
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.
|
|
<p>
|
|
Some known JAAS login modules:
|
|
<ul>
|
|
<li><u>com.sun.security.auth.module.LdapLoginModule</u> - 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.
|
|
</li>
|
|
<li><u>net.sf.jpam.jaas.JpamLoginModule</u> - (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 <i>jaas.conf</i> file.
|
|
</li>
|
|
<li><u>ghidra.server.security.loginmodule.ExternalProgramLoginModule</u> - spawns an external
|
|
program for each authentication request, and uses the external program's exit code as the indicator
|
|
of successful authentication.
|
|
<p>
|
|
There is an example (and non-useful) implementation of an external authenticator provided with
|
|
the Ghidra instalation called <i>server/jaas_external_program.example.sh</i>.
|
|
<p>
|
|
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.
|
|
<p>
|
|
The external program is fed the username\n and password\n on its STDIN (ie. 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.
|
|
</li>
|
|
<li><u>com.sun.security.auth.module.Krb5LoginModule</u> - 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.
|
|
</li>
|
|
</ul>
|
|
|
|
</LI>
|
|
<br>
|
|
<LI><u>Use of an SSH pre-shared key (<typewriter>-ssh</typewriter>)</u> is supported as an
|
|
alternate form of authentication when using Local Ghidra password (<typewriter>-a0</typewriter>).
|
|
This SSH authentication is currently supported by the Headless Analyzer only. See
|
|
<a href="#sshAuthentication">SSH User Authentication</a> for configuration details.</LI>
|
|
</UL>
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="sshAuthentication">SSH User Authentication</a></h2>
|
|
|
|
<P>
|
|
When the <typewriter>-ssh</typewriter> option has been included in conjunction with password based
|
|
authentications mode (<typewriter>-a0</typewriter> 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.,
|
|
<typewriter>id_rsa.pub</typewriter>) must be copied to the <typewriter>repositories/~ssh</typewriter>
|
|
subdirectory to a file named <typewriter><username>.pub</typewriter>. Removing the file will
|
|
eliminate SSH based authentication for the corresponding user. When creating the
|
|
<typewriter>~ssh</typewriter> 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.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="serverOptions">Server Options</a></h2>
|
|
|
|
<UL>
|
|
<LI>Networking options
|
|
<UL>
|
|
<LI><typewriter>-ip <hostname></typewriter><br>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 <i>java.rmi.server.hostname</i>.
|
|
</LI>
|
|
<br>
|
|
<LI><typewriter>-i <#.#.#.#></typewriter><br>Forces the server to be bound to a specific
|
|
IPv4 interface on the server. If specified and the <typewriter>-ip</typewriter> option is not,
|
|
the address specified by <typewriter>-i</typewriter> 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.</LI>
|
|
<br>
|
|
<LI><typewriter>-p#</typewriter><br>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.</LI>
|
|
<br>
|
|
<LI><typewriter>-n</typewriter><br>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.</LI>
|
|
</UL>
|
|
</LI>
|
|
<br>
|
|
<LI>Authentication options
|
|
<UL>
|
|
<LI><typewriter>-a#</typewriter><br>Allows a user authentication mode to be specified (see
|
|
<a href=#userAuthentication>User Authentication</a>)</LI>
|
|
<br>
|
|
<LI><typewriter>-d<ad_domain></typewriter><br>Sets the Active Directory domain name.
|
|
Example: "-dmydomain.com"</LI>
|
|
<br>
|
|
<LI><typewriter>-e#</typewriter><br>Allows the reset password expiration to be set to a
|
|
specified number of days (default is 1-day). A value of 0 prevents expiration.</LI>
|
|
<br>
|
|
<LI><typewriter>-jaas <config_file></typewriter><br>Specifies the path to the JAAS
|
|
config file (when using -a4), relative to the ghidra/server directory (if not absolute).
|
|
<p>
|
|
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.</LI>
|
|
<br>
|
|
<LI><typewriter>-u</typewriter><br>Allows the server login user ID to be specified at time of
|
|
login for <typewriter>-a0</typewriter> authentication mode. Without this option, the users
|
|
client-side login ID will be assumed.</LI>
|
|
<br>
|
|
<LI><typewriter>-autoProvision</typewriter><br>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.</LI>
|
|
<br>
|
|
<LI><typewriter>-anonymous</typewriter><br>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.</LI>
|
|
<br>
|
|
<LI><typewriter>-ssh</typewriter><br>Enable SSH as an alternate form of authentication when
|
|
using <typewriter>-a0</typewriter> authentication mode.</LI>
|
|
<br>
|
|
</UL>
|
|
</LI>
|
|
</UL>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="running_windows">Running Ghidra Server on Microsoft Windows</a></h2>
|
|
|
|
<a name="windows_scripts"><h3><u>Server Scripts (located within the server subdirectory)</u></h3></a>
|
|
<UL>
|
|
<LI><typewriter>svrInstall.bat</typewriter><br>installs server as service (<typewriter>ghidraSvr</typewriter>)</LI>
|
|
<br>
|
|
<LI><typewriter>svrUninstall.bat</typewriter><br>removes previously installed server service</LI>
|
|
<br>
|
|
<LI><typewriter>svrAdmin.bat</typewriter><br>facilitates Ghidra Server administrative commands
|
|
(see <a href="#serverAdministration">Server Administration</a>)</LI>
|
|
<br>
|
|
<LI><typewriter>ghidraSvr.bat</typewriter><br>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.</LI>
|
|
<UL>
|
|
<LI><typewriter>console</typewriter><br>starts server within the current terminal window.
|
|
<typewriter>console</typewriter> argument may be omitted to allow for double-click execution
|
|
in this mode.</LI>
|
|
<br>
|
|
<LI><typewriter>start</typewriter><br>starts the previously installed Ghidra Server service</LI>
|
|
<br>
|
|
<LI><typewriter>stop</typewriter><br>stops the installed Ghidra Server service which is
|
|
currently running</LI>
|
|
<br>
|
|
<LI><typewriter>restart</typewriter><br>stops and restarts the previously installed Ghidra
|
|
Server service</LI>
|
|
<br>
|
|
<LI><typewriter>status</typewriter><br>displays the current status of the Ghidra Server
|
|
(<typewriter>ghidraSvr</typewriter>) service</LI>
|
|
</UL>
|
|
<br>
|
|
<b>NOTE</b>: The above scripts may be run from a <typewriter>CMD</typewriter> 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
|
|
<typewriter>CMD</typewriter> shell using the <typewriter>Run as Administrator</typewriter>
|
|
action which is available by right-clicking on a command shortcut or batch file. If the
|
|
<typewriter>CMD</typewriter> shell is run in this manner, the Ghidra Server scripts may then be
|
|
executed within the shell to run with administrator privilege.
|
|
</UL>
|
|
|
|
<br>
|
|
<a name="windows_console"><h3><u>Running Server in Console Window (intended for diagnostic use only)</u></h3></a>
|
|
<P>
|
|
<b>NOTE</b>: 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.
|
|
<br><br>
|
|
If the Ghidra Server is not already running, it may be started within a console window by
|
|
running the <typewriter>ghidraSvr.bat console</typewriter> command. When you wish to terminate the
|
|
server, use the <typewriter>Ctrl-C</typewriter> key sequence within the server console window and
|
|
wait for a clean shutdown.
|
|
</P>
|
|
|
|
<br>
|
|
<a name="windows_install"><h3><u>Install as Automatic Service (<B>must have Administrator privilege</B>)</u></h3></a>
|
|
<P>
|
|
The Ghidra Server may be installed as an automatic service by executing the
|
|
<typewriter>svrInstall.bat</typewriter> script. This script may be run from a
|
|
<typewriter>CMD</typewriter> 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.
|
|
</P>
|
|
|
|
<br>
|
|
<a name="windows_uninstall"><h3><u>Uninstall Service (<B>must have Administrator privilege</B>)</u></h3></a>
|
|
<P>
|
|
If after installing the Ghidra Server as a service you wish to uninstall it, you may run the
|
|
<typewriter>svrUninstall.bat</typewriter> script. You must stop the service via the Service
|
|
Control Panel prior to running this script. This script may be run from a <typewriter>CMD</typewriter>
|
|
window, or by double-clicking the script file from an Explorer window.
|
|
</P>
|
|
<P>
|
|
<b>NOTE</b>: It is very important that you uninstall the service prior to doing any of the
|
|
following activities:
|
|
<UL>
|
|
<LI>deleting or upgrading the Ghidra installation</LI>
|
|
<LI>moving/renaming the Ghidra installation directory</LI>
|
|
</UL>
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="running_linux_mac">Running Ghidra Server on Linux or Mac-OSX</a></h2>
|
|
|
|
<a name="linux_mac_scripts"><h3><u>Server Scripts (located within the server subdirectory)</u></h3></a>
|
|
|
|
<UL>
|
|
<LI><typewriter>svrInstall</typewriter><br>installs server as service (<typewriter>ghidraSvr</typewriter>
|
|
or <typewriter>wrapper.ghidraSvr</typewriter>)</LI>
|
|
<br>
|
|
<LI><typewriter>svrUninstall</typewriter><br>removes previously installed server service</LI>
|
|
<br>
|
|
<LI><typewriter>svrAdmin</typewriter><br>facilitates administrative commands (see
|
|
<a href="#serverAdministration">Server Administration)</a></LI>
|
|
<br>
|
|
<LI><typewriter>ghidraSvr</typewriter><br>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.</LI>
|
|
<br>
|
|
<LI><typewriter>console</typewriter><br>starts server within the current terminal window</LI>
|
|
<br>
|
|
<LI><typewriter>start</typewriter><br>starts the previously installed Ghidra Server service</LI>
|
|
<br>
|
|
<LI><typewriter>stop</typewriter><br>stops the installed Ghidra Server service which is
|
|
currently running</LI>
|
|
<br>
|
|
<LI><typewriter>restart</typewriter><br>stops and restarts the previously installed Ghidra
|
|
Server service</LI>
|
|
<br>
|
|
<LI><typewriter>status</typewriter><br>displays the current status of the Ghidra Server
|
|
(<typewriter>ghidraSvr</typewriter>) service</LI>
|
|
</UL>
|
|
|
|
<br>
|
|
<a name="linux_mac_console"><h3><u>Running Server in Console Window</u></h3></a>
|
|
<P>
|
|
<b>NOTE</b>: 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.
|
|
</P>
|
|
<P>
|
|
If the Ghidra Server is not already running, it may be started within a terminal window by
|
|
running the command: <typewriter>ghidraSvr console</typewriter>. When you wish to terminate
|
|
the server, use the <typewriter>Ctrl-C</typewriter> key sequence within the server console window and
|
|
wait for a clean shutdown.
|
|
</P>
|
|
|
|
<br>
|
|
<a name="linux_mac_install"><h3><u>Install as Automatic Service (must have admin privilege)</u></h3></a>
|
|
<P>
|
|
The Ghidra Server may be installed as an automatic service by executing the
|
|
<typewriter>svrInstall</typewriter> script. Once installed, the server will start automatically
|
|
when the system is booted.
|
|
</P>
|
|
<P>
|
|
If it is preferred to run the service with a dedicated local user account, the following
|
|
entry may be added to the <i>server.conf</i> 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.
|
|
</P>
|
|
<PRE>
|
|
wrapper.app.account=<uid>
|
|
</PRE>
|
|
<P>
|
|
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 <i>uid</i> the <i>wrapper</i> process will continue
|
|
to run as <i>root</i> and monitor/manage the Java process.
|
|
</P>
|
|
<br>
|
|
<a name="linux_mac_uninstall"><h3><u>Uninstall Service (must have admin privilege)</u></h3></a>
|
|
<P>
|
|
If after installing the Ghidra Server as a service you wish to uninstall it, you may run the
|
|
<typewriter>svrUninstall</typewriter> script.
|
|
</P>
|
|
<P>
|
|
<b>NOTE</b>: It is very important that you uninstall the service prior to doing any of the following
|
|
activities:
|
|
|
|
<UL>
|
|
<LI>deleting or upgrading the Ghidra installation</LI>
|
|
<LI>moving/renaming the Ghidra installation directory</LI>
|
|
</UL>
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="serverAdministration">Server Administration</a></h2>
|
|
|
|
<P>
|
|
The script <typewriter>svrAdmin</typewriter>, or <typewriter>svrAdmin.bat</typewriter>, 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.
|
|
</P>
|
|
|
|
<P>
|
|
The general command usage is:
|
|
|
|
<PRE>
|
|
svrAdmin [<server-root-path>]
|
|
[-add <user_sid> [--p]]
|
|
[-remove <user_sid>]
|
|
[-reset <user_sid> [--p]]
|
|
[-dn <user_sid> "<user_dn>"]
|
|
[-admin <user_sid> "<repository_name>"]
|
|
[-list]
|
|
[-users]
|
|
[-migrate-all]
|
|
[-migrate "<repository_name>"]
|
|
</PRE>
|
|
</P>
|
|
|
|
<UL>
|
|
<LI><typewriter><server-root-path></typewriter><br>
|
|
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 <typewriter>svrAdmin</typewriter> script to utilize the same setting.
|
|
<br>
|
|
<LI><typewriter>-add</typewriter> <b>(Adding a User)</b><br>
|
|
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 [<typewriter>-a0</typewriter>], the
|
|
initial password is set to <typewriter>changeme</typewriter>. 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 <typewriter>-e</typewriter> <a href="#serverOptions">server option</a>).
|
|
Alternatively, the initial password may be specified by including the optional <typewriter>--p</typewriter>
|
|
parameter which will prompt for an initial password.
|
|
<br><br>
|
|
Examples:
|
|
<PRE>
|
|
svrAdmin -add mySID
|
|
svrAdmin -add mySID --p
|
|
</PRE>
|
|
</LI>
|
|
<LI><typewriter>-remove</typewriter> <b>(Removing a User)</b><br>
|
|
A user may be removed from the server with this command form. This will only prevent the
|
|
specified user from connecting to the server 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.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -remove mySID
|
|
</PRE>
|
|
</LI>
|
|
<LI><typewriter>-reset</typewriter> <b>(Reset User's Ghidra Password)</b><br>
|
|
If a user's password has expired, or has simply been forgotten, the password may be reset
|
|
to <typewriter>changeme</typewriter>. 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 <typewriter>--p</typewriter>
|
|
parameter which will prompt for an initial password.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -reset mySID
|
|
svrAdmin -reset mySID --p
|
|
</PRE>
|
|
</LI>
|
|
<LI><typewriter>-dn</typewriter> <b>(Assign User's Distinguished Name)</b><br>
|
|
The use of PKI authentication requires that each user's DN be associated with their user SID.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -dn mySID "CN=MyName,OU=AGENCY,OU=DoD,O=U.S. Government,C=US"
|
|
</PRE>
|
|
<b>NOTE</b>: After having been added to the server, a user's DN may be copied from the
|
|
<typewriter>UnknownDN.log</typewriter> file following an attempted connection with their PKCS
|
|
certificate.
|
|
</LI>
|
|
<br>
|
|
<LI><typewriter>-admin</typewriter> <b>(Adding a Repository Administrator)</b><br>
|
|
If an existing repository administrator is unable to add another user as administrator, the
|
|
server administrator may use this command to specify a new repository administrator.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -admin mySID "myProject"
|
|
</PRE>
|
|
</LI>
|
|
<LI><typewriter>-list</typewriter> <b>(List All Repositories)</b><br>
|
|
Lists all repositories. If the <i>-users</i> option is also present, the user access
|
|
list will be included for each repository.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -list
|
|
</PRE>
|
|
<LI><typewriter>-users</typewriter> <b>(List All Users)</b><br>
|
|
Lists all users with server access. May also be coupled with the <i>-list</i> option.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -users
|
|
</PRE>
|
|
</LI>
|
|
<LI><typewriter>-migrate-all</typewriter> <b>(Migrate All Repositories to Use Indexed
|
|
File-System Storage)</b><br>
|
|
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.
|
|
<br><br>
|
|
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.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -migrate-all
|
|
</PRE>
|
|
</LI>
|
|
<LI><typewriter>-migrate</typewriter> <b>(Migrate a Specified Repository to use
|
|
Indexed File-System Storage)</b><br>
|
|
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.
|
|
<br><br>
|
|
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.
|
|
<br><br>
|
|
Example:
|
|
<PRE>
|
|
svrAdmin -migrate "myProject"
|
|
</PRE>
|
|
</LI>
|
|
</UL>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="repositoryBackup">Repository Backup</a></h2>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="obsoleteCheckouts">Clearing Obsolete Checkouts</a></h2>
|
|
|
|
<P>
|
|
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
|
|
<typewriter>View Checkouts</typewriter> action is available from the popup-menu of the Ghidra
|
|
Project Window by right-clicking on a specific project file.
|
|
</P>
|
|
|
|
<P>
|
|
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:
|
|
|
|
<PRE>
|
|
find <repo-path> -name checkout.dat -exec rm {} \;
|
|
</PRE>
|
|
|
|
where <typewriter><repo-path></typewriter> is the directory path of a specific named
|
|
repository root, or the parent repositories directory if clearing checkouts for all repositories.
|
|
<br><br>
|
|
WARNING! Since the <typewriter>find</typewriter> command is recursive, care must be taken when
|
|
specifying the <typewriter><repo-path></typewriter> and the other parameters. If you specify
|
|
the incorrect <typewriter><repo-path></typewriter> or omit the correct
|
|
<typewriter>-name</typewriter> argument, you may remove important files without the ability to recover.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="pkiCertificates">PKI Certificates</a></h2>
|
|
|
|
<P>
|
|
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 <typewriter>server.conf</typewriter> to specify a <typewriter>cacerts</typewriter>
|
|
file location and each user client to
|
|
configure a user signing key/certificate keystore file. If clients wish to authenticate the server,
|
|
the <typewriter>server.conf</typewriter> must specify a server key/certificate keystore
|
|
file and each user client must configure
|
|
a <typewriter>cacerts</typewriter> file. See
|
|
<a href="#"pkiCertificateAuthorities">Managing PKI Certificate Authorities</a>
|
|
for more information on configuring a <typewriter>cacerts</typewriter> file.
|
|
</P>
|
|
|
|
<P>
|
|
User and server certificates must be acquired through one of many trusted authorities
|
|
identified by the <typewriter>cacerts</typewriter> 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 <typewriter>*.p12, *.pks,</typewriter> or <typewriter>*.pfx</typewriter> file.
|
|
</P>
|
|
|
|
<P>
|
|
User's of the Ghidra GUI application can install their key/certificate file via the
|
|
project window menu item <B>Edit->Set PKI Certificate...</B>. 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 <typewriter>analyzeHeadless</typewriter> script, see the
|
|
<typewriter>analyzeHeadlessREADME.html</typewriter> file for details.
|
|
</P>
|
|
|
|
<P>
|
|
If the Ghidra Server will be installing a server certificate, the <typewriter>server.conf</typewriter>
|
|
file should be modified to properly identify the server's key/certificate location (<i>ghidra.keystore</i>)
|
|
and password (<i>ghidra.password</i>).
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="pkiCertificateAuthorities">Managing PKI Certificate Authorities</a></h2>
|
|
|
|
<P>
|
|
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 (<typewriter>java/bin/keytool</typewriter>) or any other Java distribution. The default
|
|
cacerts keystore file location is <typewriter>Ghidra/cacerts</typewriter>
|
|
and is also specified by the <typewriter>ghidra.cacerts</typewriter> property setting within the
|
|
<typewriter>server.conf</typewriter> file. Uncomment this specification within the
|
|
<typewriter>server.conf</typewriter> file to activate use of the <typewriter>cacerts</typewriter>
|
|
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
|
|
<a href="#pkiCertificates">PKI Certificates</a>). Clients can also impose server authentication
|
|
for all HTTPS and Ghidra Server connections by creating the <typewriter>cacerts</typewriter> file
|
|
and enabling the <typewriter>ghidra.cacerts</typewriter>
|
|
property setting within the support/launch.sh and/or launch.bat scripts.
|
|
|
|
</P>
|
|
|
|
<P>
|
|
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.
|
|
</P>
|
|
|
|
<P>
|
|
Sample Base64 encoded certificate:
|
|
|
|
<PRE>
|
|
-----BEGIN CERTIFICATE-----
|
|
laSKCIElkjsudCUDusjSUkjeMSUjAJHDuLQWMCMausALkKXMXOOjSKSUjssjSKAA
|
|
ksDSDjLKJHAuemCXXUmxxqjaskuDSYRmxiqgDlakkUSUdhemjASKUakjhuEhxMSD
|
|
...
|
|
ksJKDwocQwyeEIcbzHtyrSLfoeyGCmvbNLGHpgoruSTYQafzDFTgwjkJHCXVDjdg
|
|
KDowiyYTXkcuiwCJXuyqCHpdoORriwwcCWUskucuwHDJskuejdkUWJCUDSjujsUE
|
|
-----END CERTIFICATE-----
|
|
|
|
</PRE>
|
|
</P>
|
|
|
|
<P>
|
|
You can inspect the contents of a Base64 encoded certificate file with the following command:
|
|
|
|
<PRE>
|
|
keytool -printcert -v -file <base64file>
|
|
</PRE>
|
|
|
|
where:
|
|
<UL>
|
|
<LI><typewriter><base64file></typewriter> is the file containing the Base64 encoded CA certificate to be imported.</LI>
|
|
</UL>
|
|
|
|
The Owner common name (CN) displayed by this command should be used as the alias when importing the
|
|
certificate into your cacerts file.
|
|
<br><br>
|
|
The following command should be used to add a CA certificate to a new or existing cacerts file:
|
|
|
|
<PRE>
|
|
keytool -import -alias "<caAlias>" -file <base64file> -storetype jks -keystore <cacerts-file>
|
|
</PRE>
|
|
|
|
where:
|
|
<UL>
|
|
<LI><typewriter><caAlias></typewriter> is the name of the CA corresponding to the
|
|
imported certificate.</LI>
|
|
<LI><typewriter><base64file></typewriter> is the file containing the Base64 encoded CA
|
|
certificate to be imported.</LI>
|
|
<LI><typewriter><cacerts-file></typewriter> is the cacerts file to be used by the Ghidra
|
|
Server (and/or client if needed).</LI>
|
|
</UL>
|
|
|
|
The keystore password will be requested and is used to restrict future modifications to the
|
|
<typewriter>cacerts</typewriter> file.
|
|
<br><br>
|
|
When starting the Ghidra Server with PKI authentication enabled, the CA certificates contained
|
|
within the <typewriter>cacerts</typewriter> file will be dumped to the log with their expiration dates.
|
|
</P>
|
|
|
|
<P>
|
|
Please note that the Ghidra Server does not currently support Certificate Revocation Lists (CRLs).
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="upgradeServer">Upgrading the Ghidra Server Installation</a></h2>
|
|
|
|
<P>
|
|
<OL>
|
|
<LI>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.</LI>
|
|
<br>
|
|
<LI>Uninstall an installed Ghidra Server Service by following the <typewriter>Uninstall Service</typewriter>
|
|
instructions corresponding to your operating system (<a href="#windows_uninstall">Windows</a>
|
|
or <a href="#linux_mac_uninstall">Linux/Mac-OSX</a>).</LI>
|
|
<br>
|
|
<LI>Unzip the new Ghidra distribution to a new installation directory (general unpacking and installation
|
|
guidelines may be found in <typewriter>ghidra_<I>x.x</I>/docs/InstallationGuide.html</typewriter>).</LI>
|
|
<br>
|
|
<LI>Copy the old <typewriter>repositories</typewriter> directory to the new Ghidra Server
|
|
installation directory.</LI>
|
|
<br>
|
|
<LI>Copy the <typewriter>wrapper.app.parameter.#</typewriter> lines from your old
|
|
<typewriter>server/server.conf</typewriter> file to the new installation
|
|
<typewriter>server/server.conf</typewriter>. For 5.0 release and earlier, your old
|
|
<typewriter>server.conf</typewriter> file is located within a platform-specific directory
|
|
(<typewriter>core/os/<platform></typewriter>). No other changes should be made to your new
|
|
<typewriter>server.conf</typewriter> file.
|
|
<br><br>
|
|
<B>Do not replace the new <typewriter>server.conf</typewriter> file with your old
|
|
<typewriter>server.conf</typewriter> file, as this could cause server problems.</B>
|
|
</LI>
|
|
<br>
|
|
<LI>If desired, install the Ghidra Server Service from the new installation server
|
|
subdirectory by following the instructions corresponding to your operating system
|
|
(<a href="#windows_install">Windows</a> or <a href="#linux_mac_install">Linux/Mac-OSX</a>).</LI>
|
|
</OL>
|
|
|
|
<P>
|
|
<B>WARNING!</B> <B>As of Ghidra 7.0 a new project/server storage implementation,
|
|
<typewriter>Indexed-V1</typewriter>, has been added which is not compatible with older versions of
|
|
Ghidra.</B> The <typewriter>Indexed-V0</typewriter> filesystem storage allows longer filenames and
|
|
paths to exist within a project, while the <typewriter>V1</typewriter> version expands support to
|
|
facilitate some of the very large project/repository features introduced in Ghidra 7.0. Since the
|
|
legacy storage implementation (<typewriter>Mangled</typewriter>) 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.
|
|
</P>
|
|
|
|
|
|
<P>
|
|
<B>NOTE:</B> If using Ghidra 6.0.x, opening a project which uses the newer <typewriter>Indexed-V1</typewriter>
|
|
filesystem may cause the project storage to revert to the older <typewriter>Indexed-V0</typewriter> filesystem.
|
|
</P>
|
|
|
|
<P>
|
|
A user may determine which storage implementation is used by a project by viewing the
|
|
<typewriter>Project Info</typewriter> display (via <typewriter>Project</typewriter> ->
|
|
<typewriter>View Project Info...</typewriter>). Local projects using the legacy <typewriter>Mangled</typewriter>
|
|
filesystem may be migrated to the new <typewriter>Indexed</typewriter> filesystem via this
|
|
<typewriter>Project Info</typewriter> panel. The status of Ghidra Server repositories storage can be
|
|
determined and flagged for migration via the <typewriter>server/svrAdmin</typewriter> script (described
|
|
in the <a href="#serverAdministration">Server Administration</a> section). Please note that any
|
|
migration to the <typewriter>Indexed</typewriter> filesystem storage is a one-way conversion so a
|
|
backup of your project or server repositories directory is highly recommended before proceeding.
|
|
</P>
|
|
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
<h2><a name="troubleshooting">Troubleshooting</a></h2>
|
|
|
|
<a name="checkinFailures"><h3><u>Failures Creating Repository Folders / Checking in Files</u></h3></a>
|
|
<P>
|
|
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.
|
|
</P>
|
|
<br>
|
|
|
|
<a name="connectErrors"><h3><u>Client/Server connection errors</u></h3></a>
|
|
<P>
|
|
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:
|
|
<PRE>
|
|
non-JRMP server at remote endpoint
|
|
</PRE>
|
|
|
|
<br>
|
|
<a name="windowsMissingTempDirectory"><h3><u>MS Windows - ERROR Missing Temp Directory</u></h3></a>
|
|
<P>
|
|
Running the Ghidra Server as an installed service under Windows may attempt to use a non-existing
|
|
temporary directory (e.g., <typewriter>C:\Windows\system32\config\systemprofile\AppData\Local\Temp\</typewriter>).
|
|
The work-around for this is to configure the server to use an existing temporary directory
|
|
(e.g., <typewriter>C:\Windows\Temp</typewriter>). This can be done by editing the
|
|
<typewriter>server.conf</typewriter> file, locate the <typewriter>wrapper.java.additional</typewriter>
|
|
entries and add/uncomment an entry with your temporary directory specified. For example:
|
|
<PRE>
|
|
wrapper.java.additional.3=-Djava.io.tmpdir=C:\Windows\Temp
|
|
</PRE>
|
|
Be sure to use the next unique sequence number for your <typewriter>wrapper.java.additional</typewriter> entry.
|
|
</P>
|
|
|
|
<br>
|
|
<a name="windows7and8_scriptErrors"><h3><u>MS Windows 7 and 8 - <typewriter>ghidraSvr.bat</typewriter>,
|
|
<typewriter>svrInstall.bat</typewriter>, or <typewriter>svrUninstall.bat</typewriter> Error</u></h3></a>
|
|
<P>
|
|
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:
|
|
<PRE>
|
|
Access denied: please check the user credentials
|
|
</PRE>
|
|
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 <typewriter>CMD</typewriter>
|
|
shell using the <typewriter>Run as Administrator</typewriter> action which is available by
|
|
right-clicking on a command shortcut or batch file. If the <typewriter>CMD</typewriter> 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.
|
|
</P>
|
|
|
|
<br>
|
|
<a name="selinuxDisabled"><h3><u>Linux - SELinux must be disabled</u></h3></a>
|
|
<P>
|
|
The Ghidra Server may not start properly if SELinux has not been disabled. This setting is
|
|
specified in the file <typewriter>/etc/selinux/config</typewriter>.
|
|
</P>
|
|
|
|
<br>
|
|
<a name="randomHang"><h3><u>Linux - Potential hang from /dev/random depletion</u></h3></a>
|
|
<P>
|
|
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 <i>haveged</i> (HArdware Volatile Entropy Gathering and
|
|
Expansion Daemon) which will satisfy the entropy demand needed by /dev/random.
|
|
</P>
|
|
|
|
(<a href="#top">Back to Top</a>)
|
|
<div style="border-top: 4px double; margin-top: 1em; padding-top: 1em;"> </div>
|
|
|
|
</body>
|
|
</html>
|