Bug 1092406

Attention: Nidhi

Before doing too much writing on this topic, perhaps first check the current situation regarding running JBoss EAP as a service. I believe that on RHEL and Microsoft Windows, we have native scripts which can be used to have EAP running as a service on those platforms. I could be entirely wrong, but I think it would be worth first confirming for what JSVC is used.

Created attachment 909612 [details]
standalone mode

Created attachment 909613 [details]
domain mode

Based on these comments I have created topics 
40868 - About Jsvc
40869 - Start Jsvc

and I've added them to the Administrtion and Configuration Guide.

0. 
I am missing information that this is RHEL, Solaris and HP-UX specific only.
This is not for Windows. There is prunsrv.exe (manged via service.bat) 
in Windows Native utils packages.

1.
"... is available as part of the Native Components and Native Utilities installation ..."
->
... is available as part of the Native Utilities installation ...


2.
"...Jsvc helps Java applications run more easily on Linux by managing root access. Jsvc can allow applications to switch to root to run certain commands, and subsequently change back to a non-privileged user"
->
This is misleading after reading I am not sure what to expect. 
Sentence from project doc is much clear:
"Jsvc allows the application (e.g. Tomcat) to perform some privileged operations as root (e.g. bind to a port < 1024), and then switch identity to a non-privileged user."


3.
"The instructions for starting Jsvc vary depending on whether it is being started on a Standalone or Domain mode installation"

3.1 
I am not sure with word 'installation'. I suggest smth. like:
"The instructions for starting Jsvc vary depending on whether it is being started Standalone or Domain mode"

3.2 
In case of Domain mode, Jsvc handles process of domain controller only.

4.
Prerequisites -> only Native utilities are needed.

5.
There is param '-user user-id' in all commands. User-id looks like that number is needed (uid).
Replace it with user '-user jboss' instead and declare this fact in prerequisites (2nd sentence).

6.
Stopping standalone mode
add space after '-D[Standalone]'

7.
Note -> true is if you finish EAP correctly it will be not started again. 
If finishing is not correct (like jvm crash) then EAP will be started again.

I have updated commands with regard on RPMs, I will attach them.

Another important info regarding RPMs. 
 * User must install package 'apache-commons-daemon-jsvc-eap6' 
   (command 'yum install apache-commons-daemon-jsvc-eap6')

Created attachment 914484 [details]
standalone mode - zip + rpm

Created attachment 914485 [details]
domain mode - zip + rpm

Other important thing regarding RPM. When EAP is installed via RPM owner of EAP files is user jboss -> due to I recommend:

 * In JSVC commands let 'jboss' as I suggested earlier.
 * Add note for zip installation that relevant user must be created 
   and EAP files must be set properly.

Hi Jan,
Ah! That puts a different slant on the username thing. I'll change it back.

Thanks for all the extra information. I've added the variables to the topic, and updated the instructions. I've also updated the prerequisites with the Zip information.

The new information is in topic 40869 revision 681342.

Hi Nichola,
I belive text is much better. 
Nevertheless, I see few places what we can improve.

 a] Existing sentence: "It is available as part of the Native 
    Utilities installation packages for JBoss EAP 6."
    * Native utilities is something specific for ZIP installation only.
      We need it more general with regard on RPM.
 b] There is still confusing/not-clear sentence about root access.
    See comment-8 / 2.
 c] 'Jsvc is a daemon process so it must be started as root.'
    True is any user can run jsvc daemon but in our case we want to
    be executed by root.
 d] Prerequisites, 1st para: 
    ZIP needs Native Utilities only. RPM only package
    apache-commons-daemon-jsvc-eap6. Both requires EAP standard 
    installation. How to install those artifacts he can found
    in referenced guides.
 e] Last note, If EAP6 is finished correctly then 
    Jsvc daemon is finished as well.

Jan,
I've addressed the comments above. Please note that finally, against my better judgement, I have included the line about managing root access from the project documentation. I'm not happy about it but it seems to be the only thing that will do. ;)
Cheers,
Nichola

Topics changed - 
40689 revision 682860
40868 revision 682858

Update - topic 40868 is revision 682863

The updates can be found in the Administration and Configuration Guide, revision 6.3.0-33

Link location:

https://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#chap-Jsvc

Nichola,

I belive it is better again. But we can still improve following things:

 * In new sentence remove '(e.g. Tomcat)', we don't want write 
   about Tomcat in EAP doc.
 * Structure can be better, let's talk only 'what' Jsvc is in section 8.1.1. 
   Installation is mentioned in prerequisites.
     * Move 'Note that for ZIP ... apache-commons-daemon-jsvc-eap6 package').
       to prerequisites on the end of 2nd point.
 * I am not grammar expert but wouldn't be better 
   'Jsvc is for use on RHEL, ...' instead of 'Jsvc is for use with RHEL'.
 * Modify 'be started by root.' -> 'be started by privileged user.'
 * Rename chapter 'Start and Stop Jsvc' to smth. like 'Start and Stop
   EAP by Jsvc'
 * Sentence: "...stopping Jsvc vary depending on whether it is being started 
   on a Standalone or Domain mode", replace with smth. like: 
   "... stopping EAP via Jsvc vary depending on how the server is
   being started - in a Standalone or Domain mode."
 * Replace
   "Domain mode, it handles the processes ..." ->
   "Domain mode, it handles the process ... "
 * Final note: Replace current text with:
    If JBoss EAP 6 is terminated abnormally, such as a JVM crash, 
    Jsvc will automatically restart it. If JBoss EAP 6 is terminated 
    correctly, Jsvc will be finished as well.

Verified in Revision 6.3.0-33

Notes to CCS:
Topics edited -
* 40868 - About Jsvc
* 40869 - Starting and Stopping JBoss EAP using Jsvc

Notes to QE:

I believe I have addressed all the issues raised in comment 20. Aside from resolving specific points I have: moved all prerequisites to the "Starting and Stopping.." topic, also restructured the "About Jsvc" in a more logical order, removing all mention of prerequisites.

The amended topics will be available for review in revision 6.3.0-34 (or higher) of the Administration and Configuration Guide at [1].


[1] https://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#chap-Jsvc

Russell, 

I can confirm all problems in comment-20 was fixed but there are new items:

 * EAP (via Jsvc) is started in different modes not Jsvc:
    * ... that if Jsvc is run in domain mode ...
    * ... and stop Jsvc in either standalone or domain modes ...
    * ... to start or stop Jsvc in standalone mode ...
    * ... to start or stop Jsvc in domain mode ...
 * user creation: description is not correct, I recommend target "Install 
   guide / ⁠4.2.2. Install JBoss EAP 6 (ZIP Installation)" or replace sentence
   with: "The user who will start and stop the server must have read and 
   write access to EAP installation directory."

Verified on Revision 6.3.0-35

Notes to CCS
============
Topics edited -
* 40868 - About Jsvc
* 40869 - Starting and Stopping JBoss EAP using Jsvc

Changes made:
* 40868 - Clarified the description of Jsvc a little, stating that it allows Java applications to be run as a background process.
* 40869 - Changed references to Jsvc to instead refer to JBoss EAP as relevant.

Notes to QE
===========
I believe I have addressed the issues raised in comment 23.

The amended topics will be available for review in revision 6.3.0-35 (or higher) of the Administration and Configuration Guide at [1].


[1] https://documentation-devel.engineering.redhat.com/site/documentation/en-US/JBoss_Enterprise_Application_Platform/6.3/html-single/Administration_and_Configuration_Guide/index.html#chap-Jsvc

Note to QE
==========

The changes are *ONLY* available in revision 6.3.0-36 (or higher) of the Administration and Configuration Guide.

Verified in revision 6.3.0-36 - PASSED.

Thank you all for your effort on this new chapter. Good work!