Ceptor Docs

Page tree
Skip to end of metadata
Go to start of metadata

In Ceptor Console we described the Administration GUI, but it is not the only interface available for administrating Ceptor PortalProtect. In addition, we have a command-line tool which provides limited access to the server, as well as an administration API which can be used from within a Java application.

Command-Line Access

You can execute the java class: dk.itp.portalprotect.admin.Admin – it will print its usage information similar to the following:

Requires arguments: <server address> <client name> <userid> <password> <command>
Commands:
shutdown - Shuts the entire server down
jvmdump <servername> - Asks the specified server for a JVM Dump
stop <servername> - Asks the specified server to stop itself
start <servername> - Asks the specified server to start itselflisturls <servername> [...servername] [-onelist]
- Asks the specified dispatcher for its list of recently accessed URLs. If -onelist is specified,
all entries will be concatenated into one list, sorted by date
showwebserverstatus - Lists the status of all dispatcher and their web servers.
Changewebserverstatus <dispatchers> <alternateservers> <servers> <unavailable>
- Change the “unavailable” bit on the servers – if true, the servers will be marked as being
unavailable. The dispatcher/alternateservers/servers is a name to match – use the word “all” to
match all servers.
reloadconfiguration - Ask the config server to reload its configuration.
createpdf - Create a PDF report based on the template in the xml and the timestamps given.
<xml template> <pdf filename> <from timestamp> <to timestamp>
deletestatistics <server pattern> <function pattern> [-donotdelete]
- Delete statistics entries for the specified server/functions - use to clean up specific statistics entries. Note that "all" can be used to replace *. if -donotdelete is added, it will only list the entries it would otherwise have deleted.
commitconfiguration - Ask the config server to commit any uncommitted configuration.
rollbackconfiguration - Rollback any uncommitted configuration updates - back to the active configuration.
configdiff - Show differences between active and uncommitted configuration.


Example: java dk.itp.portalprotect.admin.Admin localhost:21233 webserver1 admin password jvmdump sessionctrl1
Example: java dk.itp.portalprotect.admin.Admin localhost:21233 webserver1 admin password heapdump sessionctrl1 /tmp
Example: java dk.itp.portalprotect.admin.Admin localhost:21233 webserver1 admin password changewebserverstatus all all all true false
Example: java dk.itp.portalprotect.admin.Admin localhost:21233 webserver1 admin password createpdf report.xml myreport.pdf 01.07.2010 01.09.2010
Example: java dk.itp.portalprotect.admin.Admin localhost:21233 webserver1 admin password deletestatistics all "OLD*"


You will need the following information to be able to use it:

  • Name and port number of the configuration server.
  • Client name – must correspond to a server name defined on the configuration in the config server, and the IP address from which you run the client must be allowed to connect to the config server.
  • userid and password of a user who is allowed to execute the command you want.


Example:

java –cp PortalProtectAgent.jar;log4j.jar dk.itp.portalprotect.admin.Admin ppserver:21233 webserver1 admin password jvmdump sessionctrl1

This will connect to the config server add the address ppserver at port 21233 with the local name webserver1 and userid/password set to admin and password to obtain a JVM Dump of the JVM running the server sessionctrl1.

If you are generating PDF reports, you will need some additional files on the classpath for the charting and PDF components. These files are: jfreechart-1.0.19.jar,  jcommon-1.0.23.jar and iText-2.1.7.jar. You need to add them after log4j.jar on the command-line.

REST Access

The Ceptor administration functions can also be accessed through a REST API. More details can be found here: Ceptor REST Services - note that a newer version which supports Swagger / OpenAPI Standard is also available and should be preferred - see API Management API for details.

Programmatic Access

Ceptor PortalProtect has its own administration interface, which can be used from a Java application to query and update various information such as configuration, statistics, server status, log records etc. etc.

In reality, this API makes it possible for you to create your own application to administer PortalProtect, be it a think client, or a webapp.

This API is very powerful, the proof of which, is that Ceptor Console uses only this interface to communicate with the rest of PortalProtect.

Updated details about the API can be found in the javadoc for the dk.itp.portalprotect.admin.AdminClient class, but here is a list of the methods within the API:

Please contact Asseco Denmark if you wish to use this API for further documentation and examples on how to use it.

/**
 * Returns an array of services and their current state.
 * 
 * @see Service
 */
public Service[] listServices() throws IOException, AdminException;

/**
 * Pings all servers, returning a list of servers and their status, along with a properties object that the 
 * authentication plugins at all available sessioncontrollers have filled in. The input properties is passed to
 * each authentication plugin which can use the information to determine what to do – e.g. to actively ping backend
 * servers or just return previously cached data.
 * 
 * @param properties Passed to authentication plugin
 * @return Ping result with properties from authentication plugins ping methods.
 */
public PingResult ping(Properties properties) throws IOException, AdminException;
    
/**
 * Read log records from a logserver.
 * 
 * @param serverName Name of the logserver to read from
 * @param lastRecord null to read all records, or non-null to start reading from the specified record
 * 
 * @see org.apache.log4j.spi.LoggingEvent
 */
public LoggingEvent[] getLoggingEvents(String serverName, LoggingEvent lastRecord) throws IOException, AdminException;
    
/**
 * Returns the servers current status
 * 
 * @param serverName Name of server – which must be connected
 * @param action Action or null to get default status
 */
public ServerStatus getServerStatus(String serverName, String action) throws IOException, AdminException;
    
/**
 * Request a JVM Dump for the specified server or all connected servers<br>
 * Note that if its been less than 30 seconds since the last dump was taken on a JVM, null will be returned,
 * this is to protect the JVM from being flooded with dump requests.
 * 
 * @param serverName Server name, or null for all connected servers
 * @return JVM Dump, or null if no dump was made (because a previous dump has been made less than 30 seconds ago)
 * @throws IOException
 * @throws AdminException
 */
public String getJVMDump(String serverName) throws IOException, AdminException ;
    
/**
 * Returns the available configuration entries – each server/section contains groups which contains properties
 * 
 * @throws IOException
 */
public ServerEntry[] getConfigurationEntries() throws IOException, AdminException ;
    
/**
 * Creates a new server/section entry in the configuration.
 * 
 * @param server Server/section name.
 * @param description Description of server
 * @param extend Comma separated list of sections to extend
 * @param type Server type, “abstract” or otherwise
 * @throws IOException 
 */
public void createConfigurationServerEntry(String server, String description, String extend, String type) throws IOException, AdminException ;
    
/**
 * Updates an existing server/section entry in the configuration.
 * 
 * @param server Server/section name.
 * @param description Description of server
 * @param extend Comma separated list of sections to extend
 * @param type Server type, “abstract” or otherwise
 * @throws IOException 
 */
public void updateConfigurationServerEntry(String server, String description, String extend, String type) throws IOException, AdminException ;
    
/**
 * Deletes an existing server/section from the configuration.
 * 
 * @param server Server/section name.
 * @throws IOException 
 */
public void deleteConfigurationServerEntry(String server) throws IOException, AdminException;
    
/**
 * Creates a new group within a server.
 * 
 * @param server Name of server
 * @param group Group name
 * @param description Group description
 * @throws IOException 
 */
public void createConfigurationGroupEntry(String server, String group, String description) throws IOException, AdminException ;
    
/**
 * Updates an existing groups description.
 * 
 * @param server Name of server
 * @param group Group name
 * @param description Description
 * @throws IOException 
 */
public void updateConfigurationGroupEntry(String server, String group, String description) throws IOException, AdminException ;
    
/**
 * Deletes a group from a server.
 * 
 * @param server Name of server
 * @param group Name of group
 * @throws IOException 
 */
public void deleteConfigurationGroupEntry(String server, String group) throws IOException, AdminException ;
    
/**
 * Creates a new property in a group within a server/section
 * 
 * @param server Name of server
 * @param group Name of group
 * @param key property key
 * @param value property value
 * @param description property description
 * @throws IOException 
 */
public void createConfigurationProperty(String server, String group, String key, String value, String description) throws IOException, AdminException ;

/**
 * Úpdates the value or description of a property
 * 
 * @param server Name of server
 * @param group Name of group
 * @param key property key
 * @param value property value
 * @param description property description
 * @throws IOException 
 */
public void updateConfigurationProperty(String server, String group, String key, String value, String description) throws IOException, AdminException ;
    

/**
 * Deletes a property from a group within a server
 * 
 * @param server Name of server
 * @param group Name of group
 * @param key Name of property
 * @throws IOException 
 */
public void deleteConfigurationProperty(String server, String group, String key) throws IOException, AdminException ;

/**
 * Returns the remote statistics summary for a given server – the summary contains in-memory data from server startup
 * till now.
 * @param server Server to retrieve summary from
 * @throws IOException
 * @throws AdminException
 */
public StatisticsSummaryData getStatisticsRemoteSummaryData(String server) throws IOException, AdminException ;

/**
 * Gets the stored statistics summary – i.e. what is collected by the statistics server from the given list of
 * servers and functions in the specified time period.
 * 
 * @param servers List of server names
 * @param functions List of functions
 * @param start Start time in milliseconds
 * @param end End time in milliseconds
 * @throws IOException
 * @throws AdminException
 */
public StatisticsListData getStatisticsCollectedSummaryData(String[] servers, String[] functions, long start, long end) throws IOException, AdminException ;

/**
 * Gets the stored statistics details – i.e. what is collected by the statistics server from the given list of
 * servers and functions in the specified time period.
 * 
 * @param server Server name
 * @param function Function name
 * @param start Start time in milliseconds
 * @param end End time in milliseconds
 * @throws IOException
 * @throws AdminException
 */
public StatisticsListData getStatisticsCollectedDetails(String server, String function, long start, long end) throws IOException, AdminException ;

/**
 * Returns the list of servers that the statistics server has stored statistics for – for each server, you can
 * query the list of functions by calling <code>getStatisticsCollectedFunctions</code>.
 * @throws IOException
 * @throws AdminException
 */
public String[] getStatisticsCollectedServers() throws IOException, AdminException ;

/**
 * Returns the list of servers that the statistics server has stored statistics for – for each server, you can
 * query the list of functions by calling <code>getStatisticsCollectedFunctions</code>.
 * Note that only the servers matching the supplied pattern will be returned.
 * 
 * @param pattern Pattern to match servers for
 * @throws IOException
 * @throws AdminException
 */
public String[] getStatisticsMatchingCollectedServers(String pattern) throws IOException, AdminException;

/**
 * Returns the combined list of functions for the specified list of servers that the statistics server currently
 * has statistics stored for.
 * 
 * @param servers List of servers
 * @param pattern Pattern functions must match
 * @throws IOException
 * @throws AdminException
 */
public String[] getStatisticsMatchingCollectedFunctions(String[] servers, String pattern) throws IOException, AdminException;
    
/**
 * Resets/delete statistics for the specified list of servers and functions.
 * If functions is null, all functions for the servers will be deleted.
 * 
 * @param servers Servers to delete statistics for
 * @param functions Functions to delete statistics for, or null for all functions
 */
public void resetStatistics(String[] servers, String[] functions) throws IOException, AdminException;

/**
 * Returnes the combined list of functions for the specified list of servers that the statistics server currently
 * has statistics stored for.
 * 
 * @param servers List of servers
 * @throws IOException
 * @throws AdminException
 */
public String[] getStatisticsCollectedFunctions(String[] servers) throws IOException, AdminException ;
    
/**
 * Causes the server to shut down – usually used as part of deployment before upgrading to a newer version.
 * 
 * @throws IOException
 * @throws AdminException
 */
public void shutdownServer() throws IOException, AdminException ;

/**
 * Stops the specified server
 * 
 * @param serverName Server to stop
 * @throws IOException
 * @throws AdminException
 */
public void stopServer(String serverName) throws IOException, AdminException ;

/**
 * Starts the specified server
 * 
 * @param serverName Server to start
 * @throws IOException
 * @throws AdminException
 */
public void startServer(String serverName) throws IOException, AdminException ;

/**
 * Returns list of recently accessed URLs on a dispatcher
 * @param serverName Name of dispatcher to get list from
 * @return List of URL entries
 * @throws IOException
 * @throws AdminException
 */
public URLMemory.Entry[] getRecentAccessedURLs(String serverName) throws IOException, AdminException ;

/**
 * Retrieves the list of dispatchers, their webservers and the status of these web servers
 * 
 * @return Array of dispatchers and their webservers along with the status for these webservers
 * @throws IOException
 * @throws AdminException
 */
public WebServerStatus[] getWebServerStatus() throws IOException, AdminException;

/**
 * Changes the unavailable bit on webservers
 * 
 * @param dispatcherNames Name of one or more dispatchers - * and ? are valid
 * @param altServerNames Name of one or more alternate servers - * and ? are valid
 * @param serverNames Name of one or more servers - * and ? are valid
 * @param isUnavailable True if the server(s) should be marked as being unavailable, false if not
 * @return
 * @throws IOException
 * @throws AdminException
 */
public WebServerStatus[] updateWebServerStatus(String dispatcherNames, String altServerNames, String serverNames, 
            lean-u isUnavailable) throws IOException, AdminException;
   
/**
 * Returns and instance of the admin client which uses the specified session ID when calling methods – depending on
 * the authenticated user within the session, he does or does not have access to certain methods.
 * 
 * @param ppSessionid PortalProtect Session ID
 * @throws ConfigServerException
 * @throws IOException
 */
public static AdminClient getInstance(String ppSessionid) throws ConfigServerException, IOException ;
    
/**
 * Returns and instance of the admin client which uses the specified userid and credentials – depending on
 * the authenticated user within the session, he does or does not have access to certain methods.
 * 
 * @param user Userid
 * @param credentials User credentials
 * @throws ConfigServerException
 * @throws IOException
 */
public static AdminClient getInstance(String user, Object credentials) throws ConfigServerException, IOException ;
    
/**
 * Set the properties to be used when looking for server name, config server name,
 * and broadcast address. If not set, the system properties will be used as default.
 * 
 * @param props The properties to use
 */
public synchronized static final void setProperties(Properties props) ;

/**
 * List all security ACL's in use on a config server 
 */
public Acl[] listSecurityAcl( String serverName ) throws IOException, AdminException ;

/**
 * List all security groups in use on a config server 
 */
public Group[] listSecurityGroups( String serverName ) throws IOException, AdminException ;

/**
 * List all security users (name and description) 
 */
public String[][] listSecurityUsers( String serverName ) throws IOException, AdminException ;

/**
 * Update a security ACL in use on a config server. 
 * <p>
 * A new updated list of ACL's will be returned 
 */
public Acl[] updateSecurityAcls( String serverName, Acl acls[] ) throws IOException, AdminException ;

/**
 * Update a security Group in use on a config server.
 * <p>
 * A new updated list of Group will be returned 
 */
public Group[] updateSecurityGroups( String serverName, Group groups[] ) throws IOException, AdminException ;

/**
 * Update a security user (add or update)
 */
public void updateSecurityUser( String serverName, String name, String password, String description, String[] groups ) throws IOException, AdminException ;

/**
 * Delete a security user 
 */
public void deleteSecurityUser( String serverName, String name ) throws IOException, AdminException ;

/**
 * Reads an individual gateway destination
 */
public String readGatewayDestination(String serverName, String destinationName, boolean isActive) throws IOException, AdminException;

/**
 * Creates or updates an individual gateway destination
 */
public void createOrUpdateGatewayDestination(String serverName, String destinationName, String destination) throws IOException, AdminException;

/**
 * Deletes an individual gateway destination
 */
public void deleteGatewayDestination(String serverName, String destinationName) throws IOException, AdminException;

/**
 * Reads an individual gateway location
 */
public String readGatewayLocation(String serverName, String locationName, String[] parents, boolean isActive);

/**
 * Deletes an individual gateway location
 */
public void deleteGatewayLocation(String serverName, String locationName, String[] parents) throws IOException, AdminException;

/**
 * Creates or updates an individual gateway location
 */
public void createOrUpdateGatewayLocation(String serverName, String locationName, String[] parents, int index, String location) throws IOException, AdminException;



  • No labels