Identity Awareness Commands
Introduction
These terms are used in the CLI commands:
- PDP - The process on the Security Gateway responsible for collecting and sharing identities.
- PEP - The process on the Security Gateway responsible for enforcing network access restrictions. Decisions are made according to identity data collected from the PDP.
- AD Query - AD Query is the module responsible for acquiring identities of entities (users or computers) from the AD (Active Directory). AD Query was called Identity Logging in previous versions and in some cases is also referenced as AD Log. The adlog is the command line process used to control and monitor the AD Query feature.
test_ad_connectivity - A utility that runs connectivity tests from the Security Gateway to an AD domain controller.
The PEP and PDP processes are key components of the system. Through them, administrators control user access and network protection.
AD Query can run either on a Security Gateway that has been enabled with Identity Awareness or on a Log Server. When it runs on a Security Gateway, AD Query serves the Identity Awareness feature, and gives logging and policy enforcement. When it runs on a Log Server, AD Query gives identity logging. The command line tool helps control users’ statuses as well as troubleshoot and monitor the system.
The test_ad_connectivity utility runs over both the LDAP and WMI protocols. It is usually used by the SmartDashboard Identity Awareness first time wizard, but you can run it manually on the Security Gateway when needed.
pdp
Description These commands control and monitor the PDP process.
Syntax # pdp [command]... <parameter>
Parameter
|
Description
|
<none>
|
Display available options for this command and exit
|
debug
|
Control debug messages
|
tracker
|
Tracker options
|
connections
|
pdp connections information
|
network
|
pdp network information
|
status
|
pdp status information
|
control
|
pdp control commands
|
monitor
|
Display monitoring data
|
update
|
Recalculate users and computers group membership (deleted accounts will not be updated)
|
ad
|
Operations related to AD Query
|
timers
|
Show pdp timers information
|
pdp monitor
Description Lets you monitor the status of connected sessions. You may perform varied queries according to the usage below to get the output you are interested in.
Syntax # pdp monitor <parameter> <option>
Parameter
|
Description
|
all
|
Display information for all connected sessions
|
user <user name>
|
Display session information for the given user name
|
ip <IP address>
|
Display session information for the given IP address
|
machine <computer name>
|
Display session information for the given computer name
|
mad
|
Display all sessions that relate to a managed asset (i.e. all sessions that successfully performed computer authentication)
|
client_type [unknown|portal|"Identity Agent"|"AD Query"]
|
Display all sessions connecting via the given client type
Possible client types are:
- Unknown - User was identified by an unknown source
- Portal - User was identified by the Captive Portal
- Identity Agent - User/computer was identified by an Identity Awareness Agent
- AD Query - User was identified by AD Query
|
groups <group name>
|
Display all sessions of users / computers that are members of the given group name
|
cv_ge <version>
|
Display all sessions that are connected with a client version that is higher than (or equal to) the given version
|
cv_le <version>
|
Display all sessions that are connected via a client version that is lower than (or equal to) the given version.
|
Example
pdp monitor ip 192.0.2.1
Shows the connected user behind the given IP address (192.0.2.1).
|
Note - The last field "Published " indicates whether the session information was already published to the Gateway PEPs whose IP addresses are listed.
|
pdp connections
Description These commands assist in monitoring and synchronizing the communication between the PDP and the PEP.
Syntax # pdp connections <parameter>
Parameter
|
Description
|
pep
|
Shows the connection status of all the PEPs that should be updated by the current PDP
|
pdp control
Description Provides commands to control the PDP process.
Syntax # pdp control <parameter> <option>
Parameter
|
Description
|
revoke_ip <IP address>
|
Log out the session that is related to the given IP.
|
revoke_pt_key <session id.>
|
Revoke the packet tagging key if one exists.
|
sync
|
Force an initiated synchronization operation between the PDPs and the PEPs. When running this command, the PDP will inform its related PEPs the up-to-date information of all connected sessions. At the end of this operation, the PDP and the PEPs will contain the same and latest session information.
|
pdp network
Description Shows information about network related features.
Syntax # pdp network <parameter>
Parameter
|
Description
|
info
|
Display a list of networks known by the PDP.
|
registered
|
Display the mapping of a network address to registered gateways (PEP module).
|
pdp debug
Description Activates and deactivates the debug logs of the PDP daemon.
Syntax # pdp debug <parameter> <option>
Parameter
|
Description
|
on
|
Turn on the debug logs (should be followed by the command "set" to determine the required filter).
|
off
|
Turn off the debug logs.
|
set <topic name> [critical|surprise|
important|events|
all]…
|
Filter the debug logs that would be written to the debug file according to the given topic and severity
For debug it is recommended to run:
pdp debug set all all
Note that you can place a number of topics and severity pairs.
For example: topicA severityA topicB severityB ...
|
unset <topic name>…
|
Unset a specific topic or topics.
|
stat
|
Show the status of the debug option.
|
reset
|
Reset the debug options of severity and topic. The debug is still activated after running this command.
|
rotate
|
Rotate the log files (increase the index of each log file) so that the current log file that will be written is the PDP log. For example, pdpd.elg becomes pdpd.elg.0 and so on.
|
ccc [on|off]
|
Allows enabling or disabling writing of the CCC debug logs into the PDP log file.
|
|
Important - Activating the debug logs affects the performance of the daemon. Make sure to turn off the debug after you complete troubleshooting.
|
pdp tracker
Description Adds the TRACKER topic to the PDP logs (on by default). This is very useful when monitoring the PDP-PEP identity sharing and other communication on distributed environments. This can be set manually by adding the TRACKER topic to the debug logs.
Syntax # pdp tracker <parameter>
Parameter
|
Description
|
on
|
Turns on logging of TRACKER events in the PDP log.
|
off
|
Turns off the logging of TRACKER events in the PDP log.
|
pdp status
Description Displays PDP status information such as start time or configuration time.
Syntax # pdp status <parameter>
Parameter
|
Description
|
show
|
Display PDP information.
|
pdp update
Description Initiates a recalculation of group membership for all users and computers. Note that deleted accounts will not be updated.
Syntax # pdp update <parameter>
Parameter
|
Description
|
all
|
Recalculate group membership for all users and computers.
|
pdp ad associate
Description For AD Query, adds an identity to the Identity Awareness database on the Security Gateway. The group data must be in the AD.
Syntax # pdp ad associate ip <ip> u <username> d <domain> [m <machine>] [t <timeout>] [s]
Parameter
|
Description
|
ip <ip>
|
IP address for the identity.
|
u <username>
|
Username for the identity.
|
m <machine>
|
Computer that is defined for the identity.
|
d <domain>
|
Domain of the ID server.
|
t <timeout>
|
Timeout setting for the AD Query (default is 5 hours).
|
s
|
Associates u <username> and m <machine> parameters sequentially. First the <machine> is added to the database and then the <username>.
|
pdp ad disassociate
Description Removes the identity from the Identity Awareness database on the Security Gateway. Identity Awareness does not authenticate a user that is removed.
Syntax # pdp ad disassociate ip <ip> {u <username>|m <machine>} [r {probed|override|timeout}]
Parameter
|
Description
|
ip <ip>
|
IP address for the identity
|
u <username>
|
Username for the identity
|
m <machine>
|
Computer that is defined for the identity
|
t <timeout>
|
Timeout setting for the AD Query (default is 5 hours)
|
r {probed|override|timeout}
|
Reason that is shown in the SmartView Tracker logs
|
pep
Description Provides commands to control and monitor the PEP process.
Syntax # pep [command]... <argument>
Parameter
|
Description
|
tracker
|
Tracker options.
|
show
|
Display PEP information.
|
pep show
Description Displays information regarding pep status.
Syntax # pep show <parameter> <option>
pep show user
Description Enables monitoring the status of sessions that are known to the PEP. You can perform varied queries according to the usage below to get the output you are interested in.
Syntax # pep show user all
Parameter
|
Description
|
all
|
Display all sessions with information summary.
|
Query Syntax # pep show user query <parameter>
|
|
|
|
Parameter
|
Description
|
usr <username>
|
Display session information for the given user name.
|
mchn <computer name>
|
Display session information for the given computer name.
|
cid <IP>
|
Display session information for the given IP.
|
uid <uidString>
|
Display session information for the given session ID.
|
pdp <IP>
|
Display all session information that was published from the given PDP IP.
|
ugrp <group>
|
Display all sessions of users that are members of the given user group name.
|
mgrp <group>
|
Display all sessions of computers that are members of the given computer group name.
|
|
Note - You can use multiple query tokens (parameters) at once to create a logical "AND" correlation between them. For example, to display all users that have a sub string of "jo" AND are part of the user group "Employees" then you can use:
# pep show user query usr jo ugrp Employees
|
pep show pdp
Description Enables monitoring the communication channel between the PEP and the PDP. The output displays the connect time and the number of users that were shared through the connection.
Syntax # pep show pdp <parameter>
Parameter
|
Description
|
all
|
List all the PDPs that are connected to the current PEP with the relevant information.
|
id <IP>
|
Display connection information of the given PDP IP.
|
pep show stat
Description Shows the last time the daemon was started and the last time a policy was received.
|
Important - Each time the daemon starts, it loads the policy and the two timers (Daemon start time and Policy fetched at) will be very close.
|
Syntax # pep show stat
pep show network
Description Shows network related information.
Syntax # pep show network <parameter>
Parameter
|
Description
|
pdp
|
Shows information about mapping between the network and PDPs.
|
registration
|
Shows which networks this PEP is registered to.
|
pep debug
Description See pdp debug.
adlog
Description Provides commands to control and monitor the AD Query process.
When AD Query runs on a Security Gateway, AD Query serves the Identity Awareness feature that gives logging and policy-enforcement. In this case the command line is: adlog a <argument> (see below for options)
When it runs on a Log Server, AD Query gives identity logging. In this case, the command line is: adlog l <argument>. Note: the l in adlog l is a lowercase L.
Options for adlog a and adlog l are identical.
Syntax # adlog {a|l} <command>… <argument>
Parameter
|
Description
|
<none>
|
Display available options for this command and exit.
|
{a|l}
|
Set the working mode:
adlog l - if you are using a Log Server (identity logging)
adlog a - if you are using AD Query for Identity Awareness.
|
query
|
See sections below.
|
debug
|
dc
|
statistics
|
control
|
service_accounts
|
adlog query
Description Shows the database of identities acquired by AD Query, according to the given filter.
Usage adlog [a|l] query <argument>
Syntax
Parameter
|
Description
|
ip <IP address>
|
Filters identities relating to the given IP.
|
string <string>
|
Filters identity mappings according to the given string.
|
user <user name>
|
Filters identity mappings according to a specific user.
|
machine <computer name>
|
Filters identity mappings according to a specific computer.
|
all
|
No filtering, shows the entire identity database.
|
Example
adlog a query user jo
Shows the entry that contains the string "jo" in the user name.
adlog dc
Description Shows status of connection to the AD domain controller.
Usage adlog [a|l] dc
Syntax None
adlog statistics
Description Displays statistics regarding NT Event Logs received by adlog, per IP and by total. It also shows the number of identified IPs.
Usage adlog [a|l] statistics
Syntax None
adlog debug
Description Turns on/off debug flags for controlling the debug file. The debug file is located at $FWDIR/log/pdpd.elg (for Identity Awareness on a Security Gateway) or $FWDIR/log/fwd.elg (for identity logging on a log server).
Usage adlog [a|l] debug <parameter>
Syntax
Parameter
|
Description
|
on
|
Turn on debug.
|
off
|
Turn off debug.
|
mode
|
Show debug status (on/off).
|
extended
|
Turn on debug and add extended debug topics.
|
adlog control
Description Sends control commands to AD Query.
Usage adlog [a|l] control <parameter>
Syntax
Parameter
|
Description
|
stop
|
Stop AD Query. New identities are not acquired via AD Query.
|
reconf
|
Send a reconfiguration command to AD Query, which means it resets to policy configuration as was set in SmartDashboard.
|
adlog service_accounts
Description Shows accounts that are suspected to be "service accounts". Service accounts are accounts that don’t belong to actual users, rather they belong to services running on a computer. They are suspected as such if they are logged in more than a certain number of times.
Usage adlog [a|l] service_accounts
Syntax None
test_ad_connectivity
Description Runs connectivity tests from the Security Gateway to an AD domain controller.
Syntax $FWDIR/bin/test_ad_connectivity <parameter_1 value_1> <parameter value_2> … <parameter_n value_n>
Parameters can be set in the command line as specified below, or set in a text file located at $FWDIR/conf/test_ad_connectivity.conf . Parameters set in the test_ad_connectivity.conf file are overridden by ones provided in the command line.
|
Important - Parameters set in $FWDIR/conf/test_ad_connectivity cannot contain whitespaces and cannot be within quotation marks.
|
Output of the utility is provided in a file (not to STDOUT). The path of the file is specified by the –o parameter (see below).
Syntax
Parameter
|
Mandatory?
|
Description
|
-d <domain name>
|
Mandatory
|
Domain name of the AD, for example ad.checkpoint.com
|
-i <DC IP>
|
Mandatory
|
IP of the domain controller that is being tested.
|
-u <user name>
|
Mandatory
|
Administrator user name on the AD.
|
-o <filename>
|
Mandatory
|
Output filename relative to $FWDIR/tmp. For example, if you specify -o myfile, the output will be in $FWDIR/tmp/myfile
|
-c <password clear>
|
Either this or -a should be specified
|
User’s password.
|
-a
|
Either this or -c should be specified
|
For entering password via stdin.
|
-t <timeout>
|
Mandatory
|
Total timeout in milliseconds.
|
-D <user DN>
|
Optional
|
Use this for LDAP user DN override (the utility won’t try to figure out the DN automatically).
|
-l
|
Optional
|
Run LDAP connectivity test only (no WMI test).
|
-w
|
Optional
|
Run WMI connectivity test only (no LDAP test).
|
-s
|
Optional
|
SSL Parameters file path.
|
-L
|
Optional
|
Timeout for the LDAP test only. If this timeout expires and the LDAP test doesn’t finish, both tests fail.
|
-h
|
Optional
|
Show help.
|
|
