article Using the agentcmd utility

Related Documentation Version of up.time affected Affected Platforms
4.5 or newer All

There are two main scenarios for using the agentcmd utility:

  • With an agent on a system that has been added to up.time. In this case, the hostname is in the up.time DataStore.
  • With an agent that has been deployed on a system that has not been added to up.time. If there is no agent on the system, or there are network problems, agentcmd returns the following error message:

    ERR Unable to contact Agent ( on port 9998)

You can use agentcmd in two ways: from the command line or in an agent-side script.

Using agentcmd at the command line

The command line syntax of agentcmd is:

agentcmd <-/+s> <-p #> hostname command


  • -s = do not use an SSL connection to the agent (default).
  • +s = connect to the agent using SSL.

    If SSL is not enabled on the host, the following error message appears:

    ERR The host was not configured to use SSL

  • -p # = connect to the agent on the specified port (default is 9998).
  • hostname = the name or IP address of the host on which the agent is running.
  • command = the agent command to run.

For example, to get basic system information from an agent running on the server Solaris1, type the following command:

agentcmd +s Solaris1 sysinfo

The agent will return output similar to the following:

ARCH="SunOS Solaris1 5.9 Generic_118558-03 sun4u sparc SUNW,Ultra-Enterprise"
CPU0=" 0 - - 168 - UltraSPARC - "
CPU1=" 1 - - 168 - UltraSPARC - "
CPU4=" 4 - - 168 - UltraSPARC - "
CPU5=" 5 - - 168 - UltraSPARC - "

Using agentcmd in an agent-side script

As with netcat, agentcmd is typically used in a script on the monitoring station to perform the following tasks:

  • Contact an agent system.
  • Attempt to run a predefined agent-side script.
  • Return the results of an agent-side script.
  • Validate the status of those results.
  • Return the status to up.time.

The following example illustrates how to run agentcmd in an agent side script:

NOTE: The rexec in the command below does not indicate use of the rexec system utility. It is a keyword that is used to indicate to the agent that you are attempting to run a pre-defined command.

/usr/local/uptime4/scripts/agentcmd [-s/+s] -p [agent port] [agent hostname] rexec [password] [path]

If you use netcat in your scripts, see the following Knowledge Base articles for information on replacing netcat with agentcmd:

Related Articles

Agentcmd Logging Info Interferes With Custom Monitor Output


In 7.2 the agentcmd has extra logging enabled you are able to remove some of these logs by adding switches to the agentcmd command but the first line is always there:2013-09-19 12:50:03,704 -...

By: uptime Support | Date Created: 9-19-2013 | Last Modified: 3-15-2014 | Index: 600


What options does the addsystems utility use for WMI?


The format of options for WMI based agent-less monitoring include the following fields in addition to the standard element fields: WMI Domain (optional) WMI Username WMI Password For example:...

By: uptime Support | Date Created: 9-25-2010 | Last Modified: 8-12-2011 | Index: 513


Exporting and Importing Your DataStore or Configuration


This article explains the DataStore export and import utilities.

By: uptime Support | Date Created: 2-13-2007 | Last Modified: 12-19-2012 | Index: 140


User Comments

Subject: None

From: benr <>
Date: 3-11-2008

Comment: Some clarification on agentcmd...

1) The "command" p***ed to agentcmd should be thought of as a "keyword" or "sub-command", rather than a UNIX command or path to execute. For instance, "agentcmd somehost sysinfo" does not run the "sysinfo" UNIX command in the Uptime Agent bin directory, rather it invokes the "sysinfo" function of the agent which just so happens to use /opt/uptime-agent/bin/; this is nothing more than a coincidence.

2) The p***word for UNIX agents is set by creating a ".uptmp***wd" file in /opt/uptime-agent/bin. This is documented on the following page, buried half way down the page:

Copyright © 2021 IDERA, Inc.   Legal   Privacy Statement