From version 9.2.1 the agent requires authentication out of the box - the configuration is packaged into the WAR.
Order Do step 1 and step 2 before step 3. If the security rules are added before the user account exists.
Step 1 - Point the PC Java agent at its own user file
Open the context file you created when installing the agent:
$BOBJ_HOME/tomcat/conf/Catalina/localhost/powerconnect-java.xml
Add the Realm line, keeping the existing Environment line exactly as it is:
<Context>
<Environment name="configurationPath"
value="${catalina.home}/conf/powerconnect.properties"
type="java.lang.String"/>
<Realm className="org.apache.catalina.realm.MemoryRealm"
pathname="${catalina.home}/conf/powerconnect-users.xml"/>
</Context>
Step 2 - Create the user file
Create a new file at:
${catalina.home}/conf/powerconnect-users.xml
<tomcat-users>
<role rolename="powerconnect"/>
<user username="pcadmin" password="choose-a-password" roles="powerconnect"/>
</tomcat-users>
Choose a username and password. The role name must be powerconnect
Ensure the file is readable by the operating system account that runs Tomcat, and restrict it from everyone else. It contains a password in plain text, in the same way Tomcat's own tomcat-users.xml does.
Step 3 - Add the security rules to the installed agent
This step is only needed on installations running a version earlier than 9.2.1. Open the deployed descriptor:
$BOBJ_HOME/tomcat/webapps/powerconnect-java/WEB-INF/web.xml
Add the following three blocks immediately before the closing </web-app> tag, leaving everything already in the file unchanged:
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>PowerConnect</realm-name>
</login-config>
<security-constraint>
<display-name>PowerConnectSecurityConstraint</display-name>
<web-resource-collection>
<web-resource-name>PowerConnectResource</web-resource-name>
<url-pattern>/*</url-pattern>
</web-resource-collection>
<auth-constraint>
<role-name>powerconnect</role-name>
</auth-constraint>
</security-constraint>
<security-role>
<description>Role required to access the PowerConnect agent UI</description>
<role-name>powerconnect</role-name>
</security-role>
Step 4 - Restart Tomcat
All three files are read when Tomcat starts, so a restart is required.
Step 5 - Confirm it is working
Browse to:
http://<host>:<port>/powerconnect-java/index.html
Your browser will ask for a username and password. Enter the account from step 2 and the administration pages will load as before. If you are not prompted, clear your browser cache and try again in a private window.
What happens at the next upgrade
When you deploy version 9.2.1 or later, the new WAR replaces the agent's WEB-INF/web.xml, so the edit from step 3 is discarded and replaced by the same rules shipped in the WAR. No cleanup is needed and nothing has to be re-applied.
The files from steps 1 and 2 live outside the agent's own directory and are not touched by a deployment, so your account continues to work unchanged. This is the same reason your configurationPath setting survives upgrades today.
|
|
Survives Tomcat restart |
Survives agent upgrade |
|---|---|---|
|
|
Yes |
Yes |
|
|
Yes |
Yes |
|
|
Yes |
No - replaced by the WAR |
A plain Tomcat restart does not affect the step 3 edit. It is replaced only when a new or updated WAR is deployed, including by WDeploy.
Troubleshooting
The agent does not appear after restarting Tomcat. The user file is missing or cannot be read. Check that conf/powerconnect-users.xml exists at the location given by pathname, and that the Tomcat account can read it. Tomcat records the reason in logs/catalina.out.
The sign-in prompt reappears after entering correct details. The username or password does not match the user file, or Tomcat has not been restarted since the file was created.
Sign-in succeeds but every page returns "403 Forbidden". The roles attribute does not read exactly powerconnect. It is case-sensitive and must match the name the agent expects.
Every page returns "401 Unauthorized" and no password works. Step 3 was applied before steps 1 and 2. Complete those, then restart Tomcat.
Optional: storing the password as a hash
Tomcat can store the password as a one-way hash rather than plain text. Add a credential handler inside the same Realm element:
<Realm className="org.apache.catalina.realm.MemoryRealm"
pathname="${catalina.home}/conf/powerconnect-users.xml">
<CredentialHandler
className="org.apache.catalina.realm.MessageDigestCredentialHandler"
algorithm="SHA-256"
iterations="100000"/>
</Realm>
Generate the hashed value with the utility included in your Tomcat installation and put the result in the password attribute in place of the plain text:
Linux
$BOBJ_HOME/tomcat/bin/digest.sh -a sha-256 -i 100000 your-password
On Windows, use digest.bat. Verify sign-in works before discarding your record of the original password.
Note on authentication scope
The rules above apply only to the PowerConnect agent's own context. Your existing Tomcat users, and the configuration behind the Central Management Console, are not read, modified, or affected.
If your Tomcat already has a populated tomcat-users.xml and you would rather reuse an existing account, you can skip steps 1 and 2 entirely and instead add powerconnect to that user's roles attribute. Do not do both - a Realm declared in the context file replaces the inherited one for this context, so the agent would then read only powerconnect-users.xml and ignore tomcat-users.xml.