Here are McAfee recommendations for installing a new McAfee ePolicy Orchestrator (McAfee ePO) server or upgrading an existing instance. The first step is to download and run the latest Pre-Installation Auditor (PIA). If the PIA tool finds any issues, it will guide you to the relevant technical articles.
Note: To manually perform these checks, or if your company policy will not allow you to run the PIA tool, complete the McAfee ePO installation and patch upgrade checklist (registration required).
In addition to running the PIA tool, review these items prior to attempting a McAfee ePO upgrade:
If this is a new McAfee ePO server installation, confirm all required ports for McAfee ePO communication are open. See KB66797 for a complete list of ports needed for communication through a firewall.
Post-Installation and Upgrade
After the upgrade completes, it’s a good idea to do a quick health check on the McAfee ePO server by confirming the following:
If you have upgraded to McAfee ePO 5.9.X or later from version 5.3.3 or earlier, you need to migrate certificates from SHA-1 to SHA-2. See KB87017 for details.
Note: If you have upgraded to McAfee ePO 5.9.1 only, you need to apply McAfee ePO 5.9.1 Hotfix 1226775 before migrating your certificates. See KB90182 for details.
Backup and Recovery
If your upgrade was unsuccessful, it should roll back and leave McAfee ePO in a functional state. If the rollback also fails, you may need to perform a disaster recovery on your McAfee ePO server. The preferred method of disaster recovery is a snapshot recovery. Instructions for that can be found here.
Note: Known issue: Disaster Recovery Snapshot task fails on a clustered McAfee ePO
If you do not have a snapshot or the snapshot recovery is failing, you can follow these instructions to manually recover McAfee ePO:
Initial Setup of McAfee ePO
Are you a new user? See our available McAfee ePO training courses.
Outlined below are the initial steps to get started managing McAfee software with McAfee ePO. You can complete most of these tasks with multiple methods. The method you choose for each step depends on the size and makeup of your environment. Additional details for completing these steps can be found in Setting up your McAfee ePO environment.
- From the Server Settings section, define Proxy Settings, if required, for McAfee ePO to reach external resources.
- Check in licensed product software packages and management extensions.
- Add systems to the system tree.
- Configure and assign point product policies.
- Deploy McAfee Agent to your systems so they are under McAfee ePO management. You must install the McAfee Agent on a system before you can deploy other software.
- Deploy software to your managed systems.
- Configure product update tasks for your managed systems.
Master Repository and Management Extensions
The master repository stores the installers, updates, hotfixes, and content updates that deploy to managed systems. Checking in software to the master repository is necessary if you plan to use McAfee ePO to deploy products. The master repository is divided into three separate branches: Current, Evaluation, and Previous. The intention of the branches is to aid with product lifecycle management.
Each point product you plan to manage with McAfee ePO also includes one or more management extensions. The extensions add controls for that point product, such as policies and client tasks.
Note: If a management extension is removed, the corresponding policies and tasks you created for that product are also removed. The optional server setting Policy and Task Retention can be enabled to save policies and client task data if you remove the extension.
Building the System Tree involves two main objectives:
1. Creating and organizing groups and sub-groups
2. Adding systems
As part of the planning process, consider the best way to organize systems into groups before building the System Tree. Grouping systems with similar properties or requirements into these units allows you to manage policies and tasks for systems in one place, rather than setting policies for each system individually. For additional guidance review Considerations for Planning Your System Tree.
There are many methods to populate the System Tree. For a complete understanding of the options, review the Populating System Tree Groups sections of the McAfee ePO Product Guide.
The Lost and Found Group:
This group cannot be deleted or renamed. The sorting criteria cannot be changed from being a catchall group, although you can provide sorting criteria for any subgroups created in it. When a system is sorted into Lost and Found, it is placed in a subgroup named for the system’s domain. If no such group exists, one is created.
Creating Policies and Setting Assignments
When a product management extension is checked in, the policy catalog is updated with the policies for the corresponding point product. A read-only version named “McAfee Default” of each policy is added with an editable copy of the policy named “My Default.”
Before deploying the product to any systems, you should review the settings defined with the policy to ensure they are appropriate for your systems and make changes or create custom policies as needed. Review the Product Guide for corresponding product information about the policy settings you are working with.
When a policy has been created, it can be assigned to any group, subgroup, or individual node in the System Tree. All child subgroups in the System Tree hierarchy inherit policies set at their parent groups. These inheritance rules simplify policy and task administration. For details review the Enforcing Policies section of the Product Guide.
What Happens When You Install the Agent
Systems with a McAfee Agent installed that report to McAfee ePO are referred to as “Managed Systems.” When the McAfee Agent is installed on a client, the agent automatically initiates communication to McAfee ePO shortly after the agent services start. During the agent-server communication interval, system properties and product events are collected and sent to McAfee ePO. The list of assigned client tasks is then downloaded and added to the agent scheduler, and assigned policies are enforced. This process is repeated at every agent-server communication interval (ASCI).
McAfee ePO updates an existing System Tree record with the new properties received or adds a new record to the System Tree, if there is not already an entry present for the system. For additional details on working with the System Tree, see the System Tree section.
Deployment tasks should be completed in a phased rollout to install products to groups of systems at a time. The same task can have multiple assignments throughout the System Tree, and each assignment defines the schedule for the task.
Note: Avoid creating task schedules that will repeat the task too frequently or run the task on too many nodes simultaneously because this could potentially overload the McAfee ePO server.
When a client task is assigned to a group or node in the System Tree, the agent downloads the task settings during its next communication interval and invokes the task according to the schedule defined. When the client task is invoked, the agent downloads the components defined from the McAfee ePO server Master Repository. Additional Distributed Repositories can be configured to help split up the load.
As you deploy products to each group, monitor the deployment, run reports to confirm successful installations, and troubleshoot any problems with individual systems.
Product updates are a type of client task that are used to apply content updates to products already installed on managed systems. Content updates include antivirus definitions (.DATs), version updates, and hotfixes.
The default server task “Update Master Repository” runs daily. This task downloads the latest .DAT available from the McAfee Source Site and checks the .DAT package into the Current Branch of the Master Repository. To deploy the .DAT to the managed systems:
It is possible to transfer or move managed clients (Agents) from one McAfee ePO server in an environment to another via the Transfer Systems mechanism built in to McAfee ePO.
This is desirable when, instead of upgrading an older McAfee ePO server, the administrator chooses to build a new environment. The alternative, redeploying the McAfee Agent to all managed endpoints, can be unwieldy in larger environments.
Note: There are minimal limitations regarding McAfee ePO server versions when transferring systems. For example, it is possible to transfer from much older versions of McAfee ePO (for example, from McAfee ePO 5.1.3 to 5.9.1).
There are several critical factors to consider when transferring systems:
A step-by-step guide to configuring system transfer is detailed in KB79283.
Moving the McAfee ePO server’s SQL database to a new server or instance is not a difficult task, though it does require some familiarity with SQL configuration.
A basic walkthrough of the migration process is included in KB68427, including step-by-step instructions for implementing the basic workflow:
Note: All handlers, including the McAfee ePO server itself and all remote Agent Handlers, depend on a fast, consistent connection to the SQL database.
Don’t forget to update any remote handler’s database configuration to point to the new database; otherwise, the handler will be nonfunctional and unable to process incoming Agent communications.
A similar process is to simply move the SQL database files to a new drive or location on the SQL server (instructions are included in KB71055). This process may be necessary if the SQL server runs out of disk space.
Moving the McAfee ePO Server
In the past, the process of moving the McAfee ePO server to a new machine was arduous (see the Disaster Recovery process in KB66616 and KB71078). Those older workflows are still an option, but with the advent of the Disaster Recovery Snapshot, the recovery and migration has been consolidated into one easy process.
Considerations for the Disaster Recovery Snapshot:
Note: The “Disaster Recovery Snapshot Server” task is disabled by default when the McAfee ePO SQL database is hosted on an SQL Express instance. This is due to the SQL Express 10GB file size limitation and how much data is stored within the database inside the snapshot table.
If the McAfee ePO server is restored to a new machine, physical or virtual, it’s important to keep one method of agent-server communication intact if redeployment of the McAfee Agent is not desired. The McAfee Agent installed on client machines uses three methods of contacting the McAfee ePO server or remote handler:
If the McAfee ePO server is restored to a new machine with a different NetBIOS name and FQDN, the McAfee Agents in the environment can communicate only if the IP address remains the same. If all three methods of communication are different, the endpoints have no way of routing their traffic to the new server outside of a DNS redirect.
SHA-1 to SHA-2 Migration
McAfee ePO 5.9.x and later support the SHA-2 signing algorithm for all its self-signed certificates. If McAfee ePO 5.9.x or 5.10.x are installed cleanly, all product certificates automatically generate using this newer signing algorithm. If the McAfee ePO server is upgraded from a previous version, it is necessary to use the new functionality made possible by the Certificate Manager.
SHA-1 to SHA-2 migration is covered extensively in KB87017.
Note: It is critical that the certificate migration process described in KB87017 is not finalized before an accepted number of client machines have communicated and received the new agent-server communication certificates. Internal tracking is available within the Certificate Manager to provide for complete visibility. A failure to follow instructions during this step will result in a complete failure for all client machines that have yet to receive the new certificate to communicate with McAfee ePO —meaning that redeployment of the McAfee Agent will be the only solution.
Here are common issues McAfee ePO administrators may experience when running the Certificate Migration process:
Basic SQL maintenance can provide a measure of confidence in consistent SQL performance, a critical component of McAfee ePO performance. Because the SQL database for McAfee ePO is highly transactional in nature, the execution speed of those transactions directly relates to how fast the product is able to operate.
The Recommended Maintenance Plan (login required) for the McAfee ePO database focuses primarily on several configuration options and a regularly scheduled maintenance plan that consists of three tasks.
Configuration options recommended for the McAfee ePO SQL database:
To configure a regularly scheduled SQL maintenance plan:
Note: Creating a maintenance plan is possible in full versions of Microsoft SQL. Microsoft SQL Express is a freely available, but limited, version of Microsoft SQL. Microsoft SQL Express is only recommended for use in environments with less than 1,500 managed systems.
Rebuilding and reorganizing indexes improves SQL performance. When the database is well-maintained, database size alone does not negatively affect query performance.
Note: KB67184, the Recommended Maintenance Plan, is a registered KB and requires access to the McAfee ServicePortal. In addition to what is outlined here, the Maintenance Plan document includes an SQL script optimized for rebuilding and reorganizing indexes in production environments.
When determining the hardware specifications required for acceptable SQL performance in a McAfee ePO environment, consider the following:
Note: The SQL database can be hosted on the same machine that is responsible for hosting McAfee ePO, but this configuration is only recommended in environments with less than 10,000 managed nodes. In environments greater than 25,000 managed nodes, the SQL server should not only be separate, but also on a physical (as opposed to virtual) machine.
SQL performance itself is most closely tied to three specific hardware factors:
Hardware recommendations are difficult to estimate based on the factors described above, but in general, the SQL server should have similar, if not greater, hardware granted to it than the McAfee ePO server itself—especially memory in large environments. For example, in an environment with 75,000 to 150,000 endpoints, the standalone SQL server should have between 32GB and 128GB of memory installed, while the McAfee ePO server should have between 32GB and 64GB.
Blocking within the SQL database occurs when two transactions require access to the same resource—essentially, the transactions form a chain. When the head blocker is complete, the resource is made available again and the next transaction can move ahead.
Blocking, like SQL deadlocks, is a normal occurrence in a busy database. But, there are extreme scenarios that can arise when a blocking transaction runs for a long time. In that case, especially if the locked resource is commonly used (for example, the tables responsible for storing McAfee ePO System Tree data), the number of transactions waiting on the head blocker can grow. This condition can cause the McAfee ePO console to be unresponsive.
Note: Blocking issues are most frequently caused by inefficiencies in the design of objects within the SQL database—for example, a large table that has no index. Upgrades to McAfee ePO itself, or the point-product extension responsible for the database object, are often the first step.
Some more common blocking scenarios include:
Note: In general, index fragmentation can make a significant difference in the amount of time it takes for a transaction and how long it locks a specific resource. Refer to the section on “SQL Maintenance” or KB67184 (login required) for instructions on how to ensure fragmentation is reduced.
An SQL deadlock is a condition where two transactions are both blocked, waiting for the other transaction to complete its work and release a lock. Contention for the shared resource leads to one of the transactions being chosen as the “deadlock victim.” The transaction is killed and the deadlock victim may be immediately retried depending on the action.
Note: Deadlocks, while preferably avoided entirely, are in general a natural occurrence in a busy SQL database. Deadlocks must be addressed when they are consistent or impede McAfee ePO functionality.
Deadlocks are not clearly displayed from within the McAfee ePO console. Instead, the console might display an unexpected error or other similar problem. Deadlocks are logged in the Application Server service’s primary log, the orion.log, located in the ePO_install_dir\server\logs folder.
When deadlocks have been confirmed as a problem, it’s necessary to collect more data to resolve the problem. KB90786 (login required) describes the three methods of enabling and capturing deadlock trace information, which is necessary to provide to McAfee Support when troubleshooting a persistent deadlock problem.
Database Size & Disk Space
SQL database size considerations fall under three large branches:
Note: Database file size does not itself lead to performance problems, even in very large environments, if the SQL database is properly maintained and defragmented. SQL Express instances are commonly responsible for administrators experiencing disk size problems. With SQL Express it is necessary to first identify what is responsible for taking up the most space in the database and then remove the responsible events manually or, preferably, via McAfee ePO-configured Server Tasks.
Note: McAfee ePO 5.3.0, 5.3.1, and 5.3.2 are most commonly impacted by tempdb growth problems because they use an SQL configuration option called Snapshot Isolation. Upgrading to McAfee ePO 5.3.3 or 5.9.1 is recommended.
Disk space is also a concern during a McAfee ePO upgrade—the database can double in size during the installation process because of schema changes (especially when upgrading from McAfee ePO 5.3.x to 5.9.x and 5.10.x). KB79561 covers important considerations for preparing the database to reduce the impact of the database growth before an upgrade.
Note: Hosting the SQL database files on Windows mount points is increasing in popularity among SQL administrators. The default disk space checks that the McAfee ePO installer leverages cannot accurately detect available space on mount points; for this reason it’s necessary to use an installation switch to bypass the check.
The McAfee Agent is the client-side software that facilitates management of endpoints. Agent-server communication is the method by which system properties are uploaded to the server and new policies and client tasks are requested. When agent-server communication interval (ASCI) fails, the system is essentially unmanaged.
Note: McAfee Agent 5.x logs important ASCI information in masvc_systemname.log. For detailed information on Agent log locations including non-Windows platforms, see KB82170.
If the ASCI fails between the client (MA) and the server (McAfee ePO), review the logs from each. Use KB90603 for instructions on how to read the logs.
Commonly encountered problems with ASCI:
How to troubleshoot agent-server communication failures in McAfee Agent 5.x includes many more common causes and solutions for agent-server communication failures.
When navigating or taking action in the McAfee ePO console is slow, there are several simple but critical checks to verify:
Note: The minimum requirements detailed in documentation are just that—minimum. Depending on environment size and complexity or number of products installed and managed, your McAfee ePO or SQL server might need to be significantly more powerful than the minimum requirements.
Beyond these initial checks, troubleshooting a McAfee ePO console performance issue can be a daunting task, and will likely involve contacting McAfee Technical Support. If the administrator is comfortable working with SQL queries, see KB90786 (login required) for advanced troubleshooting and data collection techniques, including identifying the cause of SQL blocking and enabling the configuration necessary to track SQL deadlock issues.
Distributed repositories are used to provide additional sources for clients to receive both content updates (.DATs) and product deployments. When repository replication fails on a consistent basis, the impacted repositories do not match the McAfee ePO Master Repository. As a failsafe mechanism, update attempts from said repository are blocked and fail.
McAfee ePO contains a default Automatic Response that can be configured to alert the administrator via email if a replication fails: “Distributed Repository Replication fails.” If the administrator becomes aware of repeated failures to replicate to a specific repository, action must be taken to remediate.
Initial steps to begin troubleshooting a replication failure:
McAfee ePO logs detailed information about repository replication, including critical failure messages, in the ePOAPSvr_servername.log, located in the ePO_install_dir\DB\Logs directory. More complete information regarding ePO server logs is located in the McAfee ePO 5.10 Log File Reference Guide.
Common causes of repository replication failures include:
Server Tasks Running Indefinitely
McAfee ePO includes an internal, hidden server task called the dbclean task, which is responsible for terminating tasks that have reached their expiration time. There are several common issues with the dbclean task that can lead to the same symptom, such as many Server Tasks running indefinitely or far past their standard expiration time.
Note: The one exception to the above is Run Client Task Now. These tasks function differently than other server tasks—namely, they are dependent on receiving a DataChannel message from the endpoint to report on status. If this message fails to be sent or received, the tasks can stay in progress until the McAfee ePO Application Server service is restarted. For details on what this looks like and why it happens, see KB85013.
Note: While KB83384 lists McAfee ePO 5.1.2 and 5.3.1 as having resolved this problem, that refers to only one potential cause of the dbclean task becoming inactive. If the problems an administrator is experiencing match the symptoms described in the article, it’s still worth checking the status of the dbclean task via the SQL queries listed.
The Software Manager (rebranded as Software Catalog in McAfee ePO 5.10 and higher) facilitates product downloads and updates. It requires an unobstructed connection to three McAfee hosted sites over port 443 to download the installers, updates, and extensions listed:
For a full list of ports required by McAfee ePO and its core components, see KB66797.
Note: Not every release is listed in the Software Manager. Often new releases are posted only to the Product Downloads site until published at a later date to the Software Manager. Contact support if packages are expected to be listed but do not appear or downloads fail, but not if the package has simply never been posted to the Software Manager.
General tips for Software Manager navigation and usage are described in KB71608, including descriptions of easily misunderstood UI behavior. Most of these quirks have been addressed in McAfee ePO 5.10.
If the Software Manager is blank or displays an error such as “The Product Catalog has not been downloaded yet,” the certificate used to securely connect to the McAfee backend server may have failed to download. For a link to download the certificate and steps to import it manually, see KB74029.
When a single system is displayed multiple times in the McAfee ePO System Tree, it is considered a duplicate system. There are several reasons for duplicate systems—some legitimate, some not.
The first step when looking into the root cause of a duplicate systems issue is to determine if the duplicate entries are managed or unmanaged. Unmanaged entries have no system details—for example, no GUID, IP address, etc.
Note: Unmanaged duplicates are most commonly caused by an AD Sync, especially in McAfee ePO 5.3.3 and 5.9.0, which have a known issue that is resolved in McAfee ePO 5.9.1.
Managed duplicates most often arise from a situation where McAfee ePO receives properties from a managed endpoint and is unable to associate it with an existing entry in the System Tree. In other words, McAfee ePO believes the system to be new. In the standard (non-VDI mode) configuration, McAfee ePO uses the Agent GUID and MAC Address to identify existing machines, so a /forceinstall of the Agent can lead to a new GUID being generated, and potentially a new duplicate system entry.
Note: If the administrator can “checkbox” one of the managed duplicate System Tree entries and more than one of the duplicate entries are selected, this indicates that there isn’t a duplicate system at all. Instead, McAfee ePO is forced to spread a single system’s properties across multiple rows because of an unexpectedly duplicated property. For example, if McAfee VirusScan Enterprise 8.8 Patch 8 and 9 are both installed and reporting at the same time. To isolate what property is at fault, reset the column view to default (Actions – Choose Columns – Use Default).
The Master Repository Pull server task is a critical default action that is responsible for downloading content updates (.DATs, etc.) from McAfee-hosted source sites (McAfee HTTP) and checking it into the Master Repository on a regular interval.
Like distributed repository replication, rare failure is relatively normal—for example, if the backend source site is being replicated to during the time of the administrator’s repository pull, the task can fail. It is considered a best practice to schedule the Master Repository pull to run multiple times throughout the day to lessen the impact of a single failure. If the next pull succeeds, .DAT deployment in the environment is delayed only an hour, for example, instead of an entire day.
Master Repository facts:
In the rare event of a failed repository pull leading to repository corruption (unable to view packages listed in the Master Repository page, for example), consider rebuilding the Master Repository.
Note: Rebuilding the repository removes all content files and installer packages. Policies and client tasks are not impacted because this data is stored in the McAfee ePO database and tied to extensions, not the repository. It will be necessary, though, to replicate to all distributed repositories after completing a repository rebuild.
If the administrator has chosen to install McAfee ePO in an air-gapped environment, or one without access to our public repository on the web, it may be necessary to configure McAfee ePO to update from another internal server.
Another commonly requested configuration is allowing client machines to update from any McAfee ePO server in the environment. To accomplish this, it’s necessary to share the master repository keys across any McAfee ePO servers installed in the environment.
Duplicate MAC Addresses
McAfee ePO uses the MAC address of a client machine as a secondary matching mechanism—in other words, if the Agent GUID has changed, the McAfee ePO server can check existing System Tree entries for the client’s MAC address and associate the incoming properties with that entry. If both the GUID and MAC Address are not found in the McAfee ePO database, a brand-new System Tree entry is created.
If machines are legitimately reporting the same MAC address (for example, when communicating over a VPN concentrator or when deployed from a Hypervisor configured to assign the same MAC), it is undesirable for McAfee ePO to use the MAC address for matching purposes. This can be disabled entirely (though it is not recommended) or done so on an OUI-basis, as described in KB52949.
Note: Excluding a MAC OUI from being used for matching purposes does not stop a MAC address from being displayed multiple times (duplicated) as a property in the System Tree. The McAfee Agent collects information about the installed MAC address and reports it to McAfee ePO; this is expected in an environment where multiple machines have the same MAC address.
Duplicated MAC addresses can lead to issues that are often the exact opposite of a duplicate systems issue. Systems can appear to “disappear” from the System Tree, despite the Audit Log not recording any mention of the machine being deleted.
Starting with McAfee ePO 5.10, it is possible to add necessary MAC exclusions through the console directly, whereas previously it required direct SQL access. Leverage the new Add Virtual MAC Vendor page in McAfee ePO Server Settings.
Console Login or Page Not Displayed
The McAfee ePO console, hosted by the McAfee ePO Application Server service (Tomcat), is the portal through which all management features are possible. If access to the console is impossible, so is management of the environment.
Note: If the console is down, unless the other components of McAfee ePO (for example, the McAfee ePO Server service) are also nonfunctional, client machines will continue to communicate, send events and properties, and update their content if available.
Common and easily resolvable issues with console access are typically related to the browser and include:
Troubleshooting more complex console issues often comes down to one of two scenarios:
Both scenarios are covered in KB81737, though for more detailed information on troubleshooting a database connection issue, refer to the Database Connection Issues section.
Database Connection Issues
A persistent and responsive connection to the SQL database is critical for all McAfee ePO server and Agent Handler(s) functionality.
Note: McAfee ePO Best Practices define the required connection speed between a handler (including McAfee ePO) and the database to be less than 10 ms, round trip. If the required speed isn’t possible, the database or handlers must be moved to accommodate; otherwise, severely negative performance impacts will occur.
Most database connection problems can be resolved by the McAfee ePO administrator with a basic level of SQL knowledge. Common issues include:
Note: The most effective way to verify basic SQL connectivity is to use a test.udl file. The benefit of test.udl is that it exists outside of the framework of McAfee ePO and can be used to demonstrate if McAfee ePO is experiencing a software problem, or if the database connection issue exists at the SQL (or network) level. policies and client tasks.