How to set up Policy Agent 3.0 profile on FAM server using the famadm Command Line Utility?

See Policy Agents 3.0 main wiki page for more information

For a Policy Agent 3.0 and Fam 8.0 server to work together, you must first create an agent profile. The agent profile will contain the password used by the agent to communicate with the fam server, and additionally the agent profile will contain the agent's configuration information. The agent's configuration information used to be only kept in the AMAgent.property file of an agent installation in previous Policy Agents 2.2, but for 3.0 agents the configuration info for agents can be stored instead on the fam server.
When final documentation is available, we may remove this page and refer to final documents, but this will help get info to users now.
You can create an agent profile using the fam console(though this feature may not be complete yet for 3.0 agents) or you can use the fam 8.0 Command Line Utility(CLI) famadm to create an agent profile

Here are the steps to use the famadm CLI to create an agent's profile and configuartion information on the FAM 8.0 server.

Note for later editting of this page: Later, we should organize this page to show 2 options for 1) local agent configuration and profile creation and 2) centralized agent configuration and profile creation. Right now it is lumped together a bit.

These steps have been tried on FAM build 2. However, the steps and file names have been updated to reflect there state between builds 4 and 5.

0. Download the policy agent 3.0 and fam server 8.0

1. Pick up the build from nightly, and deploy the opensso.war, and configure it thru configuration jsp page.

2. Unzip the agent download AND Install the agent on your server of choice. There should be two agent config files for your installed agent, FAMAgentBootstrap.properties and FAMAgentConfiguration.properties. Note that you might be using the FAMAgentConfiguration.properties as input to the fam CLI in an upcoming step as it provides a list of needed properties to configure an agents profile.
Note: if you try to start the server where you installed the new agent, it may fail as you need to create the agent profile first (this is what this page is describing)

2-a) Please edit the installed agents FAMAgentConfiguration.properties with property values you desire as later we will use this file as input to the fam CLI.

2-b) EXPLANATION step so can skip if familiar: This step explains the configuration files mentioned in step 2 as they are used later, so its usful to understand them. These two files FAMAgentBootstrap.properties and FAMAgentConfiguration.properties are created when you install an agent and would be in a directory such as installed-agent-home/Agent001/config/ Note that in older agents like Policy Agents 2.2 there was just one configuration property file created called AMAgent.properties and it contained all the properties used by the agent.
But in the agents 3.0 it is different:
In agents 3.0 you have the option of keeping all the configuration info for an agent local (like in the two configuration property files as in the installed-agent-home/Agent001/config/) or you can keep most of the configuration info centralized in the opensso/fam/am server where you can configure agents with the opensso/fam/am server console UI or the fam CLI. This centralization of the agents configuration makes it easier to edit and is one of the big features of the agents 3.0 and opensso/fam/am server 8.0 being developed.

When you install an agent it creates two configuartion files, FAMAgentBootstrap.properties and FAMAgentConfiguration.properties, and on installation some of the property values have been set according to the answers you provided when installing the agent(like the URL of the opensso/fam/am server). Lets explain the two property config files. FAMAgentBootstrap.properties: The FAMAgentBootstrap.properties file contains a very small set of properties which are used by the agent at start up time to bootstrap itself and to also talk to the pensso/fam/am server and get any addtional configuartion info. FAMAgentConfiguration.properties. The FAMAgentConfiguration.properties file is only used if you choose to keep all your configuartion info local to the installed agent(like in the installed-agent-home/Agent001/config/ directory) and do NOT want to use the opensso server to centralize all agent configuration. If you want the local configuartion option (the older style as in agents 2.2) then you can edit the FAMAgentConfiguration.properties by editting the properties with the values you desire(just like in 2.2 agents).
So normally if you are using the new centralized agent configuration then you do not need to look at the FAMAgentConfiguration.properties as it is not used by the agent.
However, if you are planning to use centralized agent configuration, and want to use the fam CLI to create an agent profile(that is what this page is describing how to do) then you can use the FAMAgentConfiguration.properties by editting the values to configure your agent and then using this FAMAgentConfiguration.properties as input to the fam CLI (to provide info to the server about this agent's configuration. We will use this file in step 7 later.

3. Deploy, start, and and configure the opensso.war first, and then leave it running.
The opensso server needs to be running in order to do these next steps.

4. Pick up the opensso.zip from the build directory, and unzip it into a directory on your machine. There should be a file famAdminTools.zip in the tools\ directory. Create a directory called CLI and unzip the famAdminTools.zip into the directory.

5. In the CLI directory, issue the following command: setup -p <FAMconfigDirectory>,
where <FAMconfigDirectory> represents the configuration directory you specified while configuring the opensso server. If the name for <FAMconfigDirectory> contains spaces, such as "opensso directory", enclose the name in double quotation marks as such:
setup -p "opensso directory"

6. The setup will create a directory called opensso. cd to opensso/bin to find admin tool "famadm".

7. Copy FAMAgentConfiguration.properties to the bin directory, and add one line at the end of file:
userpassword=<cleartext of agent user password>
where <cleartext of agent user password> is replaced with the value of the
password you used for this agent profile, same as value in agent profile
password file ( same as value in file name you specified on agent installer)

8. Make any agent property changes necessary in this copy of FAMAgentConfiguration.properties
For local agent configuration option, this is probably not necessary as most of the agent's configuration will be stored in the local FAMAgentConfiguration.properties file that is for that agent installation(for example in j2ee_agents\appserver_v9_agent\Agent_001\config\FAMAgentConfiguration.properties) and the agent will use the values set in this local file. But for now, maybe local agents should just do this as it cant hurt.

9. Create a text file containing just the password in clear text that you use to login to opensso server with amadmin as the user name. You will refer to this file in the next step.
NOTE: on UNIX-based platforms, such as Solaris, Linux, etc., the password file should be read only owner (Therefore, you can issue a command such as the following: chmod 400 <password-file)> otherwise famadm displays an error.

10 Create agent configuration using famadm:
change to CLI\opensso\bin\ directory and run famadm

./famadm create-agent -e <realm name> -b <agent user name> -t <J2EEAgent or WebAgent> -u amadmin -f 
<amadmin user password file> -D FAMAgentConfiguration.properties

where you replace all the <...> with actual values, plus (as mentioned in step 7) you need to create a text file containing just the password in clear text that you use to login to opensso server with amadmin as user name.
For example, to create a J2EE agent profile on my machine I ran this command

./famadm create-agent -e realm1 -b mybeaagentxml -t J2EEAgent -u amadmin -f
C:\workspace\test-fam-3\opensso\tools\CLI\opensso\bin\amadminpassword.txt -D FAMAgentConfiguration.properties

11. To Show/View an agents configuration, use famadm show-agent

./famadm show-agent -e <realm name> -b <agent user name> -u amadmin -f <amadmin user password file>

to verify the agent profile account has been created correctly.
For example in my case

./famadm show-agent -e realm1 -b mybeaagentxml -u amadmin -f
C:\workspace\test-fam-3\opensso\tools\CLI\opensso\bin\amadminpassword.txt 

which will output the configuration of your agent profile you just set up.

11-a. If using local agent configuration files.
SKIP this step if you are using centralized agent configuration.
If you want to choose to use the older style agent configuration with local property files instead of the new style of storing the agents' configuartion info in the fam/opensso server, then you need to do an extra step.
EXPLANATION:
At start up time, the agent will go and contact the fam/opensso server and get configuration info, then agent will check the value of a property "com.sun.am.policy.agents.config.repository.location" and see if it is set to centralized or local. By default "com.sun.am.policy.agents.config.repository.location" is set to centralized for an agent's configuration.
For local agent config, you have to set this property on the fam/opensso server using CLI for example. This property is not kept in either of the FAMAgentBootstrap.properties or FAMAgentConfiguration.properties files, it is only stored in the fam/opensso server side agent profile and must be fetched on agent start up, and once agent reads that it is set to use local configuartion, it will then and only then read the local FAMAgentConfiguration.properties file that is for that agent installation(for example in j2ee_agents\appserver_v9_agent\Agent_001\config\FAMAgentConfiguration.properties)

AGAIN: SKIP this step and go to step 12 if using centralized agent configuration.
TO SET TO LOCAL:
first)
in step 11 you ran "famadm show-agent" and you can look at the output of that command to see what is the current setting of "com.sun.am.policy.agents.config.repository.location"
second)
update the property value to local. Step 14 describes the command to update a property of an agent's configuration, so see setp 14 for detail. The "com.sun.am.policy.agents.config.repository.location" property can take the values, "local" or "centralized". For an example command to set it to local:

./famadm update-agent -e realm1 -b mybeaagentxml -u amadmin -f
C:\workspace\test-fam-3\opensso\tools\CLI\opensso\bin\amadminpassword.txt -a
"com.sun.am.policy.agents.config.repository.location=local"

third)
do the step-1 again to "famadm show-agent" to make sure you set the property value correctly

12. Restart the Policy Agent 3.0 container again to test the agent. It should start now, since the agent profile is created.

13. work from this directory where you unzipped famadm and you can try other famadm commands

opensso\tools\CLI\opensso\bin

14 to update an agent profile
Maybe you want to update a property value. For a list of some possible property values to change, look at your agent installation FAMAgentConfiguration.properties file or run the "famadm show-agent" command in step 11.

./famadm update-agent -e realm1 -b testWebAgent1 -u amadmin -f
.pfile -a "property_name=property_value"

for example ...

./famadm update-agent -e realm1 -b mybeaagentxml -u amadmin -f
C:\workspace\test-fam-3\opensso\tools\CLI\opensso\bin\amadminpassword.txt -a
"com.sun.identity.agents.notification.enabled=false"