Overview
This article describes multiple strategies for deploying Code42 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 Code42 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
- To use these deployment tools, you need to sign in to your Code42 console as a user with the Security Administrator role.
- In the Code42 federal environment, app installations must be deployed with a deployment policy to ensure the use of FIPS encryption in the Code42 agent. Users cannot download the installation package from the Code42 console or an email message.
- Creating and using Code42 deployment policies requires familiarity with:
- Creation and configuration of organizations in your Code42 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)
-
If you install the backup agent on a device, you must also install the insider risk agent. For directions to install both agents, see Install the insider risk and backup agents. Installing only the backup agent on a device is not supported.
-
Do not restore Code42 application files backed up from one device as a means to install the insider risk agent on a different device. Application files are unique to each device and cannot be transferred to a new device.
For assistance, contact your Customer Success Manager (CSM) to engage the Code42 Professional Services team. If you don't know who your CSM is, contact our Technical Support Engineers.
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 Code42 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 Code42 cloud.
If the insider risk agent fails to connect to the Code42 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 Code42 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 Code42 cloud requires a custom script
Because user names in the Code42 cloud must be email addresses, deployments for connection to the Code42 cloud always require a customized user detection script.
- 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 Code42 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, Code42 creates a user that matches the device username.
Registration with local authentication
Use this option with Local authentication (authentication by the Code42 cloud) set in the organization's Authentication tab.
- Code42 passwords are hidden. The process described here generates Code42 passwords automatically. Those passwords are not available to users or administrators. To grant a user access to the Code42 console, an administrator needs to sign in to the Code42 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 Code42 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.The Code42 cloud requires a custom script
Because user names in the Code42 cloud must be email addresses, deployments for connection to the Code42 cloud always require a customized user detection script.
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.
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 Code42 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 Code42 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 Code42 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 Code42 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 Code42 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 Code42 environment.
- Deploy insider risk agents to the test devices and make sure they work as intended.
Verify agents can connect to the Code42 cloud
User devices must be able to reach the Code42 cloud by the HTTPS protocol. The DEPLOYMENT_URL auto-populates with the address of your Code42 environment. Check to make sure your firewalls allow client requests to reach the Code42 cloud.
Deploy to devices
Retrieve installation properties from your deployment policy as follows:
- Sign in to the Code42 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 Code42, 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 Code42 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 Code42 console.
- From the policy view in the console, you copy the arguments for a Code42 agent installer command.
- You paste or import those install arguments into your device management software and push them to devices, along with Code42 agent executables.
- When install commands run on user devices, Code42 agents retrieve your policy from the Code42 cloud.
If the Code42 agent fails to connect to the Code42 cloud and find the policy, it will retry every 5 minutes until it succeeds or a user explicitly stops the process. - Code42 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, Code42 agents start monitoring and backing up data without user intervention. Otherwise, users manually authenticate and register.
If automatic registration fails for any reason, the Code42 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 Code42 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 Code42 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 Code42 cloud requires a custom script
Because user names in the Code42 cloud must be email addresses, deployments for connection to the Code42 cloud always require a customized user detection script.
- 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 Code42 cloud must be email addresses. So you will need to modify the default user detection script to provide Code42 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, Code42 creates a user that matches the device username. That user has no password, however, and cannot restore backup data or access the Code42 console. If you cannot create a reliable script, do not attempt silent deployment. See Manual registration instead.
Silent registration with local authentication
New Code42 agents register automatically and start backups without user intervention. Use this option with local authentication (authentication by the Code42 cloud) set in the organization's Security tab.
- Code42 passwords are hidden. The process described here generates Code42 passwords automatically. Those passwords are not available to users or administrators. To grant a user access to the Code42 agent or the Code42 console, an administrator needs to sign in to the Code42 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 Code42 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.The Code42 cloud requires a custom script
Because user names in the Code42 cloud must be email addresses, deployments for connection to the Code42 cloud always require a customized user detection script.
Manual registration
Require users to manually sign in to the Code42 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 Code42 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 Code42 agents also belong to organizations. You can define customizations before or after deployment.
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 Code42 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 Code42 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 Code42 agents to.
- For each operating system you select, enter a script that identifies the username and home directory that the Code42 agent will provide when it registers with your Code42 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.
You can disable a deployment policy at any time by generating a new deployment token. The policy definition remains intact, but Code42 agents actively making requests for this policy can no longer use the policy. You must uninstall and reinstall the Code42 agent with the new deployment token to enable devices to register with this policy.
Example username detection scripts for the Code42 cloud
For example username detection scripts, see the Deployment script and command reference for the backup agent.
Step 3: Deploy Code42 agents to user devices
Before you deploy to production
Test your deployment plans
Before deploying Code42 agents to production devices, always test your entire process and all its scripts and files.
- In the Code42 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 Code42 environment.
- Deploy Code42 agents to the test devices and make sure they work as intended.
Verify agents can connect to the Code42 cloud
User devices must be able to reach the Code42 cloud by the HTTPS protocol. The DEPLOYMENT_URL auto-populates with the address of your Code42 environment. Check to make sure your firewalls allow client requests to reach the Code42 cloud.
Deploy to devices
Retrieve installation properties from your deployment policy as follows:
- Sign in to the Code42 console.
- Select Administration > Agent Management > Deployment.
- In the list of policies, click on the name of the policy you want to use.
- Copy deployment properties from the policy:
- Windows or Linux: Copy the properties and paste them into your deployment software.
- Mac: Download the deploy.properties file and provide it to your deployment process.
Distribute installation properties and Code42 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 deployment to Mac devices, see details about placing the deploy.properties file.
- For details about Code42 agent install commands, see the Deployment script and command reference for the backup agent.
Step 4: Users sign in to the Code42 agent
With the "silent registration" deployment options, users are automatically signed in to the Code42 agent.
(Not applicable to insider risk agents) With the "manual registration" deployment option, users manually sign in to the Code42 agent:
- On Windows and Mac devices, the Code42 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 Code42 agent. For details, direct users to Sign up with newly deployed Code42 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 Code42 console
Check that deployments succeed by reviewing the number of devices signed in to your organization and backing up data.
- Sign in to the Code42 console.
- Select Administration > Environment > Organizations.
- Select the organization you deployed to.
- At the top of the window, click the value under Devices.
The number of devices listed for your org should match the number of devices you deployed Code42 agents to. The quantity of data stored for each device should be greater than zero.
Review client logs
At your test devices, or a selection of your production devices, check the Code42 agent service.log.0
- 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.
- Search for
CP_ARGS=DEPLOYMENT
Find a line like the following and verify that the installer arguments are correct.CP_ARGS=DEPLOYMENT_URL=https://authority.example.com:4285&DEPLOYMENT_POLICY_TOKEN=e675f3e1-ebb3-496e-9cef-c669db6ffac6
- Search for
Results of running user script
.
Find lines like the following that verify the Code42 agent retrieved the deployment policy and ran the detection script without error.Deploy:: Successfully retrieved deployment package Results of running user script: UserScriptExecutionResults [username=exampleUser, userHomeDirectory=/home/exampleUser]
- Search for
LoginRequest
Find lines like the following that verify that the Code42 agent logged in and is authorized to backup data.UserActionRequest: LoginRequestMessage[809641607873065038] LOGIN: username=exampleUser, password=****, serverAddress=authority.example.com:4287 AUTH:: CPC session is LOGGED_IN
Troubleshooting
If a user opens the desktop UI for a newly deployed Code42 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 Code42 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 Code42 agents to.
The quantity of data stored for each device should be greater than zero.