mirror of
https://github.com/NationalSecurityAgency/ghidra.git
synced 2025-10-06 03:50:02 +02:00
Candidate release of source code.
This commit is contained in:
Dan
parent
db81e6b3b0
commit
79d8f164f8
12449 changed files with 2800756 additions and 16 deletions
210
Ghidra/RuntimeScripts/Common/server/server.conf
Normal file
210
Ghidra/RuntimeScripts/Common/server/server.conf
Normal file
|
|
@ -0,0 +1,210 @@
|
|||
#********************************************************************
|
||||
# Service Wrapper Properties
|
||||
#********************************************************************
|
||||
|
||||
# Initial Working Directory (i.e., absolute installation directory path)
|
||||
wrapper.working.dir=${ghidra_home}
|
||||
|
||||
# Mac OS X launchd plist directory
|
||||
wrapper.launchd.dir=/Library/LaunchDaemons
|
||||
|
||||
# Java Application
|
||||
wrapper.java.command=${java}
|
||||
|
||||
# Establish default permissions for generated files
|
||||
wrapper.java.umask=027
|
||||
|
||||
# Java Classpath
|
||||
include=${classpath_frag}
|
||||
|
||||
# Java Library Path (location of native authentication support libraries)
|
||||
wrapper.java.library.path.1=${os_dir}
|
||||
|
||||
# Java Additional Parameters
|
||||
wrapper.java.additional.1=-Djava.net.preferIPv4Stack=true
|
||||
|
||||
# Establishes a minimum number of rolling server.log backups to be maintained
|
||||
wrapper.java.additional.2=-DApplicationRollingFileAppender.maxBackupIndex=10
|
||||
|
||||
# Ensure that classpath_frag is defined for service startup
|
||||
wrapper.java.additional.3=-Dclasspath_frag=${classpath_frag}
|
||||
|
||||
# A suitable cacerts file must be installed when using PKI authentication
|
||||
#wrapper.java.additional.4=-Dghidra.cacerts=./Ghidra/cacerts
|
||||
|
||||
# If Ghidra clients must authenticate the server, the server will need to install
|
||||
# a server key/certificate in a secure location (e.g., /etc/pki/...)
|
||||
# and specify the location and password via the properties below.
|
||||
# Be sure to properly set permissions on the Ghidra installation and this file
|
||||
# if using these settings.
|
||||
#wrapper.java.additional.5=-Dghidra.keystore=
|
||||
#wrapper.java.additional.6=-Dghidra.password=
|
||||
|
||||
# Temporary Directory Setting - uncomment the following setting to override the Java default.
|
||||
# This may be necessary on certain Windows platforms when installing as a service.
|
||||
#wrapper.java.additional.7=-Djava.io.tmpdir=C:\\Windows\\Temp
|
||||
|
||||
# Enable/Disable use of compression for DataBuffer serialization and Block Streams
|
||||
wrapper.java.additional.8=-Ddb.buffers.DataBuffer.compressedOutput=true
|
||||
|
||||
# Uncomment to enable remote debug support
|
||||
# The debug address will listen on all network interfaces, if desired the '*' may be
|
||||
# set to a specific interface IP address (e.g., 127.0.0.1) if you wish to restrict.
|
||||
# During debug it may be necessary to increase timeout values to prevent the wrapper
|
||||
# from restarting the server due to unresponsiveness.
|
||||
#wrapper.java.additional.9=-Xdebug
|
||||
#wrapper.java.additional.10=-Xnoagent
|
||||
#wrapper.java.additional.11=-Djava.compiler=NONE
|
||||
#wrapper.java.additional.12=-Xrunjdwp:transport=dt_socket\,server=y\,suspend=n\,address=*:18200
|
||||
#wrapper.startup.timeout=0
|
||||
#wrapper.ping.timeout=0
|
||||
|
||||
# Optional debug enablement instead of using the wrapper.java.additional arguments above
|
||||
# This will cause application to start in a suspended state in debug mode and increase
|
||||
# timeouts to their maximum values.
|
||||
#wrapper.java.debug.port=18200
|
||||
|
||||
# Uncomment to enable remote use of jvisualvm for profiling
|
||||
# See JMX documentation for more information: http://docs.oracle.com/javase/8/docs/technotes/guides/management/agent.html
|
||||
#wrapper.java.additional.13=-Dcom.sun.management.jmxremote.port=9010
|
||||
#wrapper.java.additional.14=-Dcom.sun.management.jmxremote.local.only=false
|
||||
#wrapper.java.additional.15=-Dcom.sun.management.jmxremote.authenticate=false
|
||||
#wrapper.java.additional.16=-Dcom.sun.management.jmxremote.ssl=false
|
||||
|
||||
# YAJSW will by default assume a POSIX spawn for Linux and Mac OS X systems, unfortunately it has
|
||||
# not yet been implemented for Mac OS X. The default process support within YAJSW for Mac OS X is
|
||||
# broken so we must force the use of BSD process support which appears to work properly. To enable
|
||||
# this mode of operation the wrapper.fork_hack option must be enabled and the wrapper.posix_spawn
|
||||
# option explicitly disabled. The ghidraSvr script will attempt to make these changes automatically
|
||||
# for Mac OS X.
|
||||
#wrapper.fork_hack=true
|
||||
|
||||
# Pipe server output to console/log
|
||||
#wrapper.console.pipestreams=true
|
||||
|
||||
# Monitor for Deadlock
|
||||
wrapper.java.monitor.deadlock = true
|
||||
|
||||
# Main server application class
|
||||
wrapper.java.app.mainclass=ghidra.server.remote.GhidraServer
|
||||
|
||||
# Initial Java Heap Size (in MB)
|
||||
wrapper.java.initmemory=396
|
||||
|
||||
# Maximum Java Heap Size (in MB)
|
||||
# See svrREADME.txt file for advice (Server Memory Considerations)
|
||||
wrapper.java.maxmemory=768
|
||||
|
||||
# Specify the directory used to store repositories. This directory must be dedicated to this
|
||||
# Ghidra Server instance and may not contain files or folders not produced by the
|
||||
# Ghidra Server or its administrative scripts. Relative paths originate from the
|
||||
# Ghidra installation directory, although an absolute path is preferred if not using default.
|
||||
# This variable is also used by the svrAdmin script.
|
||||
|
||||
ghidra.repositories.dir=./repositories
|
||||
|
||||
# Ghidra server startup parameters.
|
||||
#
|
||||
# Command line parameters: (Add command line parameters as needed and renumber each starting from .1)
|
||||
# [-ip###.###.###.###] [-p#] [-a#] [-anonymous] [-ssh] [-d<ntDomain>] [-e<days>] [-u] [-n] <repositories_path>
|
||||
#
|
||||
# -ip###.###.###.### : ip address to bound to (by default, uses IP address bound to hostname)
|
||||
# -p# : base TCP port to be used (default: 13100)
|
||||
# -a# : an optional authentication mode where # is a value 0 or 2
|
||||
# 0 - Private user password
|
||||
# 2 - PKI Authentication
|
||||
# -anonymous : enables anonymous repository access (see svrREADME.html for details)
|
||||
# -ssh : enables SSH authentication for headless clients
|
||||
# -e<days> : specifies default password expiration time in days (-a0 mode only, default is 1-day)
|
||||
# -u : enable users to be prompted for user ID (does not apply to -a2 PKI mode)
|
||||
# -n : enable reverse name lookup for IP addresses when logging (requires proper configuration
|
||||
# of reverse lookup by your DNS server)
|
||||
# ${ghidra.repositories.dir} : config variable (defined above) which identifies the directory
|
||||
# used to store repositories. Use of this variable to define the
|
||||
# repositories directory must be retained.
|
||||
wrapper.app.parameter.1=-a0
|
||||
wrapper.app.parameter.2=${ghidra.repositories.dir}
|
||||
|
||||
# Establish server process owner
|
||||
# This should only be used when installing as a service using a nologin
|
||||
# local user account. Establishing a suitable account is left as a
|
||||
# system administration task. NOTE: the use of this feature is not
|
||||
# yet supported for Windows installations.
|
||||
#wrapper.app.account=ghidra
|
||||
|
||||
#********************************************************************
|
||||
# Service Wrapper Logging Properties
|
||||
#********************************************************************
|
||||
# Format of output for the console. (See docs for formats)
|
||||
wrapper.console.format=PM
|
||||
|
||||
# Log Level for console output. (use INFO to see Ghidra Server activity)
|
||||
wrapper.console.loglevel=INFO
|
||||
|
||||
# Provide additional wrapper debug logging info
|
||||
#wrapper.debug=true
|
||||
|
||||
# Log file to use for wrapper output logging.
|
||||
wrapper.logfile=wrapper.log
|
||||
|
||||
# Format of output for the log file. (See docs for formats)
|
||||
wrapper.logfile.format=LPTM
|
||||
|
||||
# Log Level for wrapper.log file output. (See docs for log levels)
|
||||
wrapper.logfile.loglevel=INFO
|
||||
|
||||
# Maximum size that the log file will be allowed to grow to before
|
||||
# the log is rolled. Size is specified in bytes. The default value
|
||||
# of 0, disables log rolling. May abbreviate with the 'k' (kb) or
|
||||
# 'm' (mb) suffix. For example: 10m = 10 megabytes.
|
||||
wrapper.logfile.maxsize=10m
|
||||
|
||||
# Maximum number of rolled log files which will be allowed before old
|
||||
# files are deleted. The default value of 0 implies no limit.
|
||||
wrapper.logfile.maxfiles=10
|
||||
|
||||
#********************************************************************
|
||||
# Service Wrapper Windows Properties
|
||||
#********************************************************************
|
||||
# Title to use when running as a console
|
||||
wrapper.console.title=Ghidra Server
|
||||
|
||||
#********************************************************************
|
||||
# Service Wrapper Windows NT/2000/XP Service Properties
|
||||
#********************************************************************
|
||||
# WARNING - Do not modify any of these properties when an application
|
||||
# using this configuration file has been installed as a service.
|
||||
# Please uninstall the service before modifying this section. The
|
||||
# service can then be reinstalled.
|
||||
|
||||
# Name of the service
|
||||
wrapper.ntservice.name=ghidraSvr
|
||||
|
||||
# Display name of the service
|
||||
wrapper.ntservice.displayname=Ghidra Server
|
||||
|
||||
# Description of the service
|
||||
wrapper.ntservice.description=Repository server for Ghidra data files.
|
||||
|
||||
# Service dependencies. Add dependencies as needed starting from 1
|
||||
wrapper.ntservice.dependency.1=
|
||||
|
||||
# Mode in which the service is installed.
|
||||
wrapper.ntservice.starttype=AUTO_START
|
||||
|
||||
# Linux service daemon priority for Ghidra Server (start/stop)
|
||||
# It is important that the network interface has started and any file-system
|
||||
# dependencies are mounted prior to the Ghidra Server starting.
|
||||
# NOTE: uninstall the Ghidra Server service using svrUninstall script before changing
|
||||
# the property wrapper.daemon.update_rc or wrapper.daemon.run_level_dir property.
|
||||
wrapper.daemon.update_rc= 98 05
|
||||
|
||||
# Linux service daemon link directories
|
||||
wrapper.daemon.run_level_dir=/etc/rcX.d
|
||||
|
||||
# Allow the service to interact with the desktop.
|
||||
wrapper.ntservice.interactive=false
|
||||
|
||||
# Restart failed service after 1 minute delay
|
||||
wrapper.ntservice.failure_actions.actions=RESTART
|
||||
wrapper.ntservice.failure_actions.actions_delay=60000
|
||||
920
Ghidra/RuntimeScripts/Common/server/svrREADME.html
Normal file
920
Ghidra/RuntimeScripts/Common/server/svrREADME.html
Normal file
|
|
@ -0,0 +1,920 @@
|
|||
<!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="#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>
|
||||
It is also highly recommended that the server's local hostname (with and with domain name) be
|
||||
mapped to its IP address with the hosts file (<typewriter>/etc/hosts</typewriter> on Linux). If
|
||||
this is not desirable for your setup, then the server should be explicitly bound to a specific IP
|
||||
address (see the <typewriter>-ip</typewriter> parameter in the <a href="#serverOptions">Server
|
||||
Options</a> section).
|
||||
</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:
|
||||
|
||||
<OL>
|
||||
<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>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).
|
||||
</LI>
|
||||
<br>
|
||||
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.
|
||||
<br><br>
|
||||
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.
|
||||
<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>
|
||||
</OL>
|
||||
</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><typewriter>-a#</typewriter><br>Allows a user authentication mode to be specified (see
|
||||
<a href=#userAuthentication>User Authentication</a>)</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>
|
||||
<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>-ip<#.#.#.#></typewriter><br>Forces the server to be bound to a specific
|
||||
IP address on the server. This option is required when a server has multiple IP interfaces.</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>-e#</typewriter><br>Allows the reset password expiration to be set to a
|
||||
specified number of days (default is 1-day).</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>
|
||||
|
||||
(<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>]
|
||||
[-remove <user_sid>]
|
||||
[-reset <user_sid>]
|
||||
[-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>).
|
||||
<br><br>
|
||||
Example:
|
||||
<PRE>
|
||||
svrAdmin -add mySID
|
||||
</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).
|
||||
<br><br>
|
||||
Example:
|
||||
<PRE>
|
||||
svrAdmin -reset mySID
|
||||
</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 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="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>
|
||||
Loading…
Add table
Add a link
Reference in a new issue