GP-394 Added svrAdmin grant and revoke repository access command support. Added Ghidra Server asynchronous command processing and improved svrAdmin -list command usage.

2026-05-27 16:26:28 +08:00 · 2022-03-15 14:35:38 -04:00
parent ee268dea09
commit 8446a00aff
8 changed files with 1015 additions and 653 deletions
@@ -30,6 +30,7 @@ typewriter {
  <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="#serverLogs">Server Logs</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>
@@ -42,7 +43,7 @@ typewriter {
    <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>
+  <LI><a href="#running_linux_mac">Running Ghidra Server on Linux or Mac OS</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>
@@ -55,7 +56,7 @@ typewriter {
  <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>
+  <LI><a href="#troubleshooting">Troubleshooting / Known Issues</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>
@@ -64,6 +65,7 @@ typewriter {
 	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>
+	<LI><a href="#macDiskAccess">Mac OS - Service fails to start (macOS 10.14 Mojave and later)</a></LI>
  </UL>
 </UL>

@@ -149,6 +151,16 @@ new installation.  Using a non-default repositories directory outside your Ghidr
 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="serverLog">Server Logs</a></h2>
+
+<P>The Ghidra Server produces two log files, which for the most part have the same content.
+The service <i>wrapper.log</i> file generally resides within the Ghidra installation root 
+directory, while the <i>server.log</i> file resides within the configured <i>repositories</i> 
+directory.  When running the server in console mode all <i>wrapper.log</i> output is directed
+to the console.
+
 (<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>
@@ -490,7 +502,10 @@ are not currently supported.

 (<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>
+<h2><a name="running_linux_mac">Running Ghidra Server on Linux or Mac OS</a></h2>
+
+<B>NOTE:</B> Mac OS has limited support.  The latest supported version is macOS 10.13.x High Sierra 
+(see <a href="#macDiskAccess">Mac OS - Service fails to start</a>).</u>

 <a name="linux_mac_scripts"><h3><u>Server Scripts (located within the server subdirectory)</u></h3></a>

@@ -584,7 +599,15 @@ to run as <i>root</i> and monitor/manage the Java process.
 <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.
+    command shell so that the proper command line arguments may be specified.  This command
+    should only be used after the corresponding Ghidra installation has been properly 
+    configured via modification of the <typewriter>server/server.conf</typewriter> file
+    (see <a href="#serverConfig">Server Configuration</a>) and installed and/or started.  
+</P><P>
+    Many of the commands are queued for subsequent execution by the Ghidra Server process.
+    Due to this queing, there may be a delay between the invocation of a <typewriter>svrAdmin</typewriter>
+    command and its desired affect.  The Ghidra log file(s) may be examined for feedback on 
+    queued command execution (see <a href="#serverLogs">Server Logs</a>).
 </P>

 <P>
@@ -592,12 +615,14 @@ to run as <i>root</i> and monitor/manage the Java process.

    <PRE>
    svrAdmin [&lt;server-root-path&gt;]
-             [-add &lt;user_sid&gt; [--p]] 
+             [-add &lt;user_sid&gt; [--p]]
+             [-grant &lt;user_sid&gt; &lt;"+r"|"+w"|"+a"&gt; &lt;repository_name&gt;] 
+             [-revoke &lt;user_sid&gt; &lt;repository_name&gt;] 
             [-remove &lt;user_sid&gt;] 
             [-reset &lt;user_sid&gt; [--p]] 
             [-dn &lt;user_sid&gt; &quot;&lt;user_dn&gt;&quot;]
-             [-admin &lt;user_sid&gt; &quot;&lt;repository_name&gt;&quot;]
-             [-list]
+             [-list  &lt;user_sid&gt; [&lt;user_sid&gt;...]]
+             [-list [--users]]
             [-users]
             [-migrate-all]
             [-migrate &quot;&lt;repository_name&gt;&quot;]
@@ -626,11 +651,29 @@ to run as <i>root</i> and monitor/manage the Java process.
        svrAdmin -add mySID --p
    </PRE>
    </LI>
+    <LI><typewriter>-grant</typewriter>&nbsp;&nbsp;<b>(Grant Repository Access for User)</b><br>
+    Grant access for a specified user and repository where both must be known to the server.
+    Repository access permission must be specified as +r for READ_ONLY, +w for WRITE or +a for ADMIN.
+    Examples:
+    <PRE>
+        svrAdmin -grant mySID +a myRepo
+        svrAdmin -grant mySID +w myRepo
+    </PRE>
+    </LI>
+    <LI><typewriter>-revoke</typewriter>&nbsp;&nbsp;<b>(Revoke Repository Access for User)</b><br>
+    Revoke the access for a specified user and named repository.  Currently, revoking access for a 
+    user does not disconnect them if currently connected.
+    Examples:
+    <PRE>
+        svrAdmin -revoke mySID myRepo
+    </PRE>
+    </LI>
    <LI><typewriter>-remove</typewriter>&nbsp;&nbsp;<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 
+    A user may be removed from the Ghidra Server and all repositories with this command form.  This will only prevent the 
+    specified user from connecting to the server in the future and will have no effect on the state or history 
    of repository files.  If a repository admin wishes to clear a user&apos;s checkouts, this is 
-    a separate task which may be performed from an admin&apos;s Ghidra client.
+    a separate task which may be performed from an admin&apos;s Ghidra client.  Currently, removing a 
+    user does not disconnect them if currently connected.
    <br><br>
    Example:
    <PRE>
@@ -661,26 +704,19 @@ to run as <i>root</i> and monitor/manage the Java process.
    <typewriter>UnknownDN.log</typewriter> file following an attempted connection with their PKCS 
    certificate.
    </LI>
-    <br>
-    <LI><typewriter>-admin</typewriter>&nbsp;&nbsp;<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>&nbsp;&nbsp;<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.
+    <LI><typewriter>-list</typewriter>&nbsp;&nbsp;<b>(List All Repositories and/or User Permissions)</b><br>
+    If the <i>--users</i> option is also present, the complete user access
+    list will be included for each repository. Otherwise, command may be followed by one or user SIDs (separated by a space)
+    which will limit the displayed repository list and access permissions to those users specified.
    <br><br>
    Example:
    <PRE>
        svrAdmin -list
+        svrAdmin -list --users
+        svrAdmin -list mySID
    </PRE>
    <LI><typewriter>-users</typewriter>&nbsp;&nbsp;<b>(List All Users)</b><br>
-    Lists all users with server access.  May also be coupled with the <i>-list</i> option.
+    Lists all users with server access.
    <br><br>
    Example:
    <PRE>
@@ -894,7 +930,7 @@ Please note that the Ghidra Server does not currently support Certificate Revoca
    <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>
+    or <a href="#linux_mac_uninstall">Linux/Mac OS</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>
@@ -953,7 +989,7 @@ backup of your project or server repositories directory is highly recommended be

 (<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>
+<h2><a name="troubleshooting">Troubleshooting / Known Issues</a></h2>

 <a name="checkinFailures"><h3><u>Failures Creating Repository Folders / Checking in Files</u></h3></a>
 <P>
@@ -1028,7 +1064,7 @@ Expansion Daemon) which will satisfy the entropy demand needed by /dev/random.
 </P>

 <br>
-<a name="macDiskAccess"><h3><u>Mac OS - Service fails to start</u></h3></a>
+<a name="macDiskAccess"><h3><u>Mac OS - Service fails to start (macOS 10.14 Mojave and later)</u></h3></a>
 <P>
 The installed service may fail to start with Mac OS Majave (10.14) and later due
 to changes in the Mac OS system protection feature.  When the service fails to start it does not