Overview
This article describes multiple strategies for deploying agents to user devices. You can integrate your apps with SSO, for example, without user intervention. The article is intended for administrators using device management tools like SCCM for Windows or Jamf Pro for Mac. This article provides:
- Introduction to agent deployment and description of how it works in general.
- Links to help you with specific environments and specific deployment strategies.
For simplified instructions, see:
Considerations
- Creating and using deployment policies requires familiarity with:
- Creation and configuration of organizations in your environment.
- The authentication methods that your organizations use to manage users.
- The process you use to distribute and install applications to user devices (typically a device management tool like SCCM for Windows or Jamf for Mac)
Insider risk agent
How deployment works
Before selecting a deployment option, it helps to understand how deployment works from end-to-end:
- You define a deployment policy in the Incydr console.
- From the policy view in the console, you copy the arguments for an insider risk agent installer command.
- You paste or import those install arguments into your device management software and push them to devices, along with insider risk agent executables.
- When install commands run on user devices, insider risk agents retrieve your policy from the Incydr cloud.
If the insider risk agent fails to connect to the Incydr cloud and find the policy, it will retry every 5 minutes until it succeeds or a user explicitly stops the process. - Insider risk agents run your policy's detection script in order to determine usernames, home directories, and optionally, organizations.
- After a policy automatically registers users, insider risk agents start monitoring data.
If automatic registration fails for any reason, the insider risk agent retries every hour. It retrieves the policy again and tries to register again until it succeeds.
Select a deployment option
The deployment options available vary with your environment's configuration:
- Whether you authenticate users with SSO or local authentication.
- Whether and how the deployment's username detection script matches usernames at devices with usernames in your authentication data.
Following are the most common deployment options:
Registration with SSO
Use this option with SSO authentication set in the organization's Authentication tab.
- In the deployment policy's user detection script, SSO usernames are email addresses.
You must customize the installer's detection script to adjust for that.
- The deployment policy's user detection script matches usernames at devices with usernames in SSO data.
Usernames on endpoint devices must match usernames in SSO data, and usernames for the Incydr cloud must be email addresses. So you will need to modify the default user detection script to provide insider risk agents with usernames that match SSO usernames. See Step 2, below.Mismatched usernames cause serious errors
If the detection script cannot provide a precise match with SSO data, Incydr creates a user that matches the device username.
Registration with local authentication
Use this option with Local authentication (authentication by the Incydr cloud) set in the organization's Authentication tab.
- Incydr passwords are hidden. The process described here generates passwords automatically. Those passwords are not available to users or administrators. To grant a user access to the Incydr console, an administrator needs to sign in to the Incydr console and edit the user data to set a new password.
- You must customize your deployment policy's detection script to specify the user's email address.
Usernames must be email addresses. In your deployment policy, you must modify the default user detection script. The script needs to take in device usernames and output email addresses. See Step 2, below.
Step 1: Identify the deployment organization
A deployment policy belongs to an organization. When you assign an organization to a deployment policy:
- The organization's authentication method is the policy's authentication method.
- When deployed insider risk agents install, users and devices become members of that organization.
- An organization has one deployment policy only. Child organizations do not inherit their parents' policies.
Changing the organization can break the policy
Once an organization has a deployment policy, changing the organization's authentication method can easily break the policy. See Deployment policies reference.
Once an organization has a deployment policy, changing the organization's authentication method can easily break the policy. See Deployment policies reference.
Check configuration of the organization:
- Sign in to the Incydr console.
- Select Administration > Environment > Organizations, and select an organization.
Note the organization name. You will need it later. - Verify settings on the organization's Authentication tab:
- Verify that the Authentication method setting is correct for your selected deployment option:
- Registration with SSO: SSO
- Registration with local authentication: Local
- If you need to change the settings, click the Edit icon
.
- Verify that the Authentication method setting is correct for your selected deployment option:
Step 2: Create the deployment policy
Define the deployment policy for the organization you identified in Step 1.
- In the Incydr console, select Administration > Agent Management > Deployment.
- Click Create deployment policy.
- In Deployment policy name enter a name to identify the deployment policy. Since a deployment policy is associated with an organization, include the organization's name in the policy.
- Select the Registration organization for the policy.
If your organization's name does not appear in the list, that organization already has a policy.
You can edit or delete that existing policy. - In User detection scripts select one or more operating systems that you will deploy insider risk agents to.
- For each operating system you select, add a custom batch/bash script. Provide a script that identifies the username and home directory that the insider risk agent will provide when it registers with your environment. For example scripts, see Deployment script and command reference for the insider risk agent. The script must end by echoing the username and user home directory in accordance with your selected deployment option:
- Registration with SSO:
echo C42_USERNAME=<value> echo C42_USER_HOME=<value>
- Registration with local authentication:
echo C42_USERNAME=<email@address> echo C42_USER_HOME=<value>
- Registration with SSO:
- Click Create.
The policy is created. - In the Details tab, review the deployment policy and click Edit if you need to make changes:
-
Deployment properties contain important pieces of information needed for the deployment and are placed in the deployment properties file:
- DEPLOYMENT_URL: The Incydr cloud where the organization's tenant resides.
- DEPLOYMENT_POLICY_TOKEN: The policy's authorization token.
- DEPLOYMENT_SECRET: The authorization token for registration. The deployment secret authorizes the agent and limits the time in which an agent can register.
- Command-line arguments (Windows) displays the arguments format needed on Windows machines.
-
Deployment properties contain important pieces of information needed for the deployment and are placed in the deployment properties file:
- In the Scripts tab, review the user detection script and click Edit if you need to make changes. This script associates a username with the device, and can be customized to fit a number of deployment scenarios. For example scripts, see Deployment script and command reference for the insider risk agent.
Step 3: Deploy insider risk agents to user devices
Before you deploy to production
Test your deployment plans
Before deploying insider risk agents to production devices, always test your entire process and all its scripts and files.
- In the Incydr console, create at least one test organization.
- Add several test users to that organization.
- Connect test devices for those users to the network that includes your environment.
- Deploy insider risk agents to the test devices and make sure they work as intended.
Verify agents can connect to the Incydr cloud
User devices must be able to reach the Incydr cloud by the HTTPS protocol. The DEPLOYMENT_URL auto-populates with the address of your environment. Check to make sure your firewalls allow client requests to reach the Incydr cloud.
Deploy to devices
Retrieve installation properties from your deployment policy as follows:
- Sign in to the Incydr console.
- Select Administration > Agent Management > Deployment.
- In the list of policies, select the policy you want to use.
- Copy deployment properties, arguments, and scripts from the policy and place them in your device management software so they can be pushed to devices along with insider risk agent executables.
- Click Download properties file.
- Place the downloaded properties file in one of the following locations on user devices (choose one location only for each operating system):
- Windows:
- C:\Windows\Temp\code42.deployment.properties
- C:\ProgramData\Code42-AAT-Config\code42.deployment.properties
- Mac:
- /tmp/code42.deployment.properties
- /Library/Application Support/Code42-AAT-Config/code42.deployment.properties
- Linux:
- /tmp/code42.deployment.properties
- /var/opt/code42-aat-config/code42.deployment.properties
- Windows:
- Distribute installation properties and insider risk agent installers to your target devices. Then run the installers.
Details for those two tasks depend on your device management tool and endpoint operating systems. Consult the vendor's documentation for your device management tool. For details about insider risk agent install commands, see the Deployment script and command reference for the insider risk agent.
Once the deployment is successful, the insider risk agent is registered with Incydr, and the insider risk agent deletes the deployment properties file.
Step 4: Verify deployment
Check that deployments succeed by reviewing logs and the number of devices deployed to your organization.
Review logs
Review logs in the following file locations on the endpoints:
- Windows: C:\ProgramData\Code42-AAT\Data\logs\
- Mac: /Library/Application Support/Code42-AAT/Data/logs/
- Linux: /var/opt/code42-aat/data/logs
Check the number of devices deployed
- Sign in to the Incydr console.
- Select Administration > Environment > Organizations.
- Select the organization you deployed to.
- At the top of the window, click the value under Agents.
The number of devices listed for your org should match the number of devices you deployed insider risk agents to.
Backup agent
How deployment works
Before selecting a deployment option, it helps to understand how deployment works from end-to-end:
- You define a deployment policy in the Incydr console.
- From the policy view in the console, you copy the arguments for a agent installer command.
- You paste or import those install arguments into your device management software and push them to devices, along with agent executables.
- When install commands run on user devices, agents retrieve your policy from the Incydr cloud.
If the agent fails to connect to the Incydr cloud and find the policy, it will retry every 5 minutes until it succeeds or a user explicitly stops the process. - agents run your policy's detection script in order to determine usernames, home directories, and optionally, organizations.
- When a policy is configured to automatically register users, agents start monitoring and backing up data without user intervention. Otherwise, users manually authenticate and register.
If automatic registration fails for any reason, the agent retries every hour. It retrieves the policy again and tries to register again, until it succeeds or a user explicitly stops the process.
Select a deployment option
The deployment options available vary with your environment's configuration:
- Whether you authenticate users with SSO or local authentication.
- Whether and how the deployment's username detection script matches usernames at devices with usernames in your authentication data.
Following are the most common deployment options:
Silent registration with SSO
New agents register automatically and start monitoring and backups without user intervention. Use this option with SSO authentication and local directory services set in the organization's Security tab.
- In the deployment's username detection script, SSO usernames are email addresses.
You must customize the installer's detection script to adjust for that.
- The deployment's username detection script matches usernames at devices with usernames in SSO data.
Usernames on endpoint devices need to match usernames in SSO data, and usernames for the Incydr cloud must be email addresses. So you will need to modify the default user detection script to provide agents with usernames that match SSO usernames. See Step 2, below.Mismatched usernames cause serious errors
If the detection script cannot provide a precise match with SSO data, Incydr creates a user that matches the device username. That user has no password, however, and cannot restore backup data or access the Incydr console. If you cannot create a reliable script, do not attempt silent deployment. See Manual registration instead.
Silent registration with local authentication
New agents register automatically and start backups without user intervention. Use this option with local authentication (authentication by the Incydr cloud) set in the organization's Security tab.
- Incydr passwords are hidden. The process described here generates passwords automatically. Those passwords are not available to users or administrators. To grant a user access to the agent or the Incydr console, an administrator needs to sign in to the Incydr console and edit the user data to set a new password.
- You must customize your deployment's detection script to specify the user's email address.
Usernames must be email addresses. In your deployment policy, you need to modify the default user detection script. The script needs to take in device usernames and output email addresses. See Step 2, below.
Manual registration
Require users to manually sign in to the agent. Use this option with:
- Local authentication set in the organization's Security tab, and user-defined names and passwords.
- SSO.
Step 1: Identify the deployment organization
A deployment policy belongs to an organization. When you select or create that organization:
- The organization's authentication method is the policy's authentication method.
- When deployed agents install, users and devices become members of that organization.
- An organization has one deployment policy only. Child organizations do not inherit their parents' policies.
- Custom images and texts for agents also belong to organizations. You can define customizations before or after deployment.
Changing the organization can break the policy
Once an organization has a deployment policy, changing the organization's authentication method can easily break the policy. See Deployment policies reference.
Once an organization has a deployment policy, changing the organization's authentication method can easily break the policy. See Deployment policies reference.
Check configuration of the organization:
- Sign in to the Incydr console.
- Select Administration > Environment > Organizations, and select an organization.
Note the organization name; you will need it later. - Select the Authentication tab and verify that the settings are correct for your selected deployment option:
- Silent registration with SSO: The Authentication method must be SSO.
- Silent registration with local authentication: The Authentication method must be Local.
- Manual registration: The Authentication method must be Local.
- Click Cancel (or Save, if you made changes).
- Verify the device backup defaults settings:
- Click Actions menu and select Device backup defaults.
- Select the Backup tab and verify that DESTINATIONS lists at least one destination name and is set to Use.
The other possible value, DESTINATIONS ... Auto-start, is not acceptable. It means silent deployment is not possible. To configure destinations, go to the organization's action menu, select Device Backup Defaults > Backup > Destinations. - Select the Network tab and note whether PROXY is enabled; you will need that information later.
- Click Cancel (or Save, if you made changes).
Step 2: Create the deployment policy
Define the deployment policy for the organization you identified in Step 1.
- In the Incydr console, select Administration > Agent Management > Deployment.
- Select Create New Deployment Policy or Create deployment policy.
The prompt differs depending on whether you see the initial welcome screen or your list of existing policies. - Enter a Deployment policy name to describe this policy.
- At Registration organization select the organization you identified at Step 1, above.
If your organization's name does not appear in the menu, that organization already has a policy.
You can edit or delete that existing policy. - At Do you want to automatically register users?, verify that the settings are correct for your selected deployment option:
- Silent registration with SSO: Yes
- Silent registration with local authentication: Yes
- Manual registration: No
- At Select one or more operating systems, select the systems you will deploy agents to.
- For each operating system you select, enter a script that identifies the username and home directory that the agent will provide when it registers with your environment. For details, see the script reference.
The script must end by echoing the username and user home directory in accordance with your selected deployment option:- Silent registration with SSO:
echo C42_USERNAME=<value> echo C42_USER_HOME=<value>
- Silent registration with local authentication:
echo C42_USERNAME=<email@address.tld> echo C42_USER_HOME=<value>
- Manual registration
echo C42_USERNAME=<value> echo C42_USER_HOME=<value>
- Silent registration with SSO:
- At Do your clients need a proxy URL to connect to the Code42 cloud?, select No or Yes, depending on what you determined at Step 1, above.
- At Launch desktop app after initial install?, select the correct value for your selected deployment option:
- Silent registration with SSO: No
- Silent registration with local authentication: No
- Manual registration: Yes
- Click Create.
You can view the policy and copy the installation properties at any time.
To disable a deployment policy, generate a new deployment token
You can disable a deployment policy at any time by generating a new deployment token. The policy definition remains intact, but agents actively making requests for this policy can no longer use the policy. You must uninstall and reinstall the agent with the new deployment token to enable devices to register with this policy.
You can disable a deployment policy at any time by generating a new deployment token. The policy definition remains intact, but agents actively making requests for this policy can no longer use the policy. You must uninstall and reinstall the agent with the new deployment token to enable devices to register with this policy.
Example username detection scripts for the Incydr cloud
Step 3: Deploy agents to user devices
Before you deploy to production
Test your deployment plans
Before deploying agents to production devices, always test your entire process and all its scripts and files.
- In the Incydr console, create at least one test organization.
- Add several test users to that organization.
- Connect test devices for those users to the network that includes your environment.
- Deploy agents to the test devices and make sure they work as intended.
Verify agents can connect to the Incydr cloud
User devices must be able to reach the Incydr cloud by the HTTPS protocol. The DEPLOYMENT_URL auto-populates with the address of your environment. Check to make sure your firewalls allow client requests to reach the Incydr cloud.
Deploy to devices
Step 4: Users sign in to the agent
With the "silent registration" deployment options, users are automatically signed in to the agent.
(Not applicable to insider risk agents) With the "manual registration" deployment option, users manually sign in to the backup agent:
- On Windows and Mac devices, the agent opens on the desktop automatically.
- On Linux, users should run this command:
/usr/local/crashplan/bin/CrashPlanDesktop
Instruct users to provide names and passwords as prompted by the agent. For details, direct users to Sign up with newly deployed agent.
Step 5: Verify deployment
For silent registration deployment options
Perform the following verification steps if you use the following silent deployment options:
- Silent registration with SSO
- Silent registration with local authentication
Review device data in Incydr console
Review client logs
Troubleshooting
If a user opens the desktop UI for a newly deployed agent, but the UI never progresses beyond the message Connecting... , then the deployment has probably failed.
Confirm the error as follows:
- Find service.log.0 in one of these locations:
-
Windows: C:\ProgramData\CrashPlan\log
To view this hidden folder, open a file browser and paste the path in the address bar. If you installed per user, see the file and folder hierarchy. -
Mac: /Library/Logs/CrashPlan
If you installed per user, see the file and folder hierarchy. - Linux: /usr/local/crashplan/log
-
Windows: C:\ProgramData\CrashPlan\log
- Open service.log.0 with a text editor.
- Find deployment errors by searching for
Deploy::, for example:deploy:: Unable to make request
Deploy:: Unable to process deployment package, USERNAME_NOT_IN_OUTPUT
For the manual registration deployment option
If you use the manual registration deployment option, after users sign in, check that deployments succeed by reviewing the number of devices signed in to your organization and backing up data.
- Sign in to the Incydr console.
- Select Administration > Environment > Organizations.
- Select the organization you deployed to.
- At the top of the window, click the value under Agents.
The number of devices listed for your org should match the number of devices you deployed agents to.
The quantity of data stored for each device should be greater than zero.