Egnyte Desktop App Mass Configuration is designed to help administrators deploy consistent drive mappings, connected folders, and offline folders across multiple user devices. By using a centralized configuration file, administrators can automate settings deployment via Mobile Device Management (MDM) or other configuration management tools. This feature simplifies the management of configurations for large-scale environments, ensuring that end-users receive the correct setup without manual intervention.

Available Configuration Options

General Flow of the Feature

      Administrator's Role

      End-User Experience

Preparing the Configuration File

Sample Configuration

Available Configuration Options

Exporting Configuration via CLI

Deployment Instructions

      Deploying the Configuration via Installer

      Deploying Manually via File Copy

      Ready-to-use configuration

Edge Cases and Conflict Handling

Logs and Notifications Overview

Widget indicators and restrictions

      Widget indicator

      Widget action restrictions

      Applying and removing configuration

Troubleshooting and logs

 

Available Configuration Options

1. Domain (Mandatory)
2. Drive Letter (Mandatory)
3. Drive Label (Mandatory)
4. SSO Settings
5. Cloud Start Path
6. Connected Folders
7. Offline Folders
8. Drive adding restriction

 

General Flow of the Feature

Administrator's Role

The administrator prepares the configuration file that defines settings such as drive mappings, connected folders, and offline folders. This file can be generated via CLI from an admin machine or manually created in JSON format depending on the organizational requirements.

The configuration file is then deployed to user machines via MDM (or similar tools). Once deployed, the configuration automatically applies during Egnyte Drive startup on the user’s machine.

End-User Experience

• The configuration is applied silently when the Egnyte Desktop App starts. Users will receive a notification confirming the deployment from their admin.
• A special drive icon will appear in the drives list, indicating that the drive is managed by the admin and cannot be modified by the user.
• Users cannot disconnect or remove the configured drive or folders. 
• Admin-managed connected and offline folders are also locked for user modification. These folders are marked with a distinct icon, showing that they are part of the mass deployment.

 

Preparing the Configuration File

Before deploying the configuration, the administrator needs to prepare the configuration file, which will contain all necessary settings for the Desktop App setup.

Sample Configuration

The configuration file defines several parameters, including drives, connected folders, and offline folders. Below is a sample configuration and a breakdown of key components:

 

Available Configuration Options

Domain (mandatory)

"Domain":  "<domain>.egnyte.com"

This is a mandatory parameter. It signifies the Egnyte domain to which the drive will be mounted. 

 

Drive Letter (mandatory)

"DriveLetter":  "Z:"

The letter assigned to the drive (For example: 'Z:'). Letters A, B and C are restricted for the OS and cannot be used when mounting.

Important Notice: Drive Letter as the Primary Identifier

The drive letter acts as the primary identifier for drive configurations within the system, as specified in the JSON configuration file. Configurations are tracked and updated based on the drive letter, ensuring that any modifications affect only the corresponding drive. Applying the same configuration to a different drive letter creates a separate configuration specific to the new drive.

Example Use Case:

• Consider a scenario where Drive Z is configured with specific settings, such as a custom label and additional properties.
• If the configuration for Drive Z is modified (i.e. changing the label or properties), these changes will overwrite the existing configuration associated with Drive Z, as the system identifies configurations by the drive letter.
• If the same initial configuration for Drive Z is applied to Drive P, the system will treat this as a new configuration for Drive P, distinct from Drive Z.

 

Drive Label (mandatory)

"Label":  "Egnyte Drive"

This is a mandatory parameter. It signifies the label which will be used by the Mounted drive, which must be unique and under 30 characters.

Available values:

String

 

UseSSO

"UseSSO":  false

This setting determines whether Single Sign-On (SSO) should be used for authentication. When set to true, SSO login will be enforced. SSO must be enabled for the user; otherwise, the login attempt will fail. This setting is optional and defaults to false.

Available values:

true

false

 

CloudStartPath

"CloudStartPath":  "/Shared"

This option defines the default starting path for the mounted drive. In the example, mounted drive will display the top most level folder “/Shared”. If the user is expected to begin from the "/Shared/Finance" folder within their drive, the code should be modified to the following:

"CloudStartPath":  "/Shared/Finance"

Available values:

String

If there is a need to use a filepath specific to a user, like “/Private/jsmith”, it is possible to use ::egnyte_username:: tag. Please see this section for the details. 

 

Connected Folders

This option allows the Admin to configure Connected Folders for the mounted drive. In the example above, there are two Connected folders added, but there is no lower or upper limit to how many can be connected which can be modified by adding or removing additional folder configurations. Each connected folder consists of the following structure:

Cloud Path

 "CloudPath":  "/Private/::egnyte_username::/Documents"

The Cloud Path specifies a location within the Egnyte cloud where a folder will be connected. In this example, we're linking to each user's Private directory, requiring their username. To facilitate deployment to various users, we use the special tag ::egnyte_username::, which dynamically inserts the respective username into the path. Please see this section for the details. 

For instance if the drive has been added for user jsmith, then the folder will be connected to /Private/jsmith/Documents folder.

Available values:

String

Create Child (Optional)

 "CreateChild": false

The "Create Child" setting determines whether the local folder connects directly to the specified cloud path or is created as a subfolder. For example, consider a local folder named "Photos" intended to sync with a cloud folder called "Gallery".

When the "Create Child" option is set to false, the contents of the local "Photos" folder sync directly into the "Gallery" folder in the cloud. This means that opening the "Gallery" folder in the cloud will display all the photos from the local folder alongside any pre-existing files or photos in "Gallery." Additionally, other files and folders within "Gallery" will sync to the local folder.

If the "Create Child" option is set to true, the system creates a new subfolder within the "Gallery" folder, named after the local folder, such as "Photos." The contents of the local "Photos" folder are then synced into this new "Gallery/Photos" subfolder. This ensures that when accessing the "Gallery" folder in the cloud, the "Photos" subfolder is clearly separated from other files in "Gallery."

Available values:

true

false

Local Path

"LocalPath": "~/Documents"

"LocalPath":  "C:\\Users\\::windows_username::\\Desktop\\"

Local Path specifies a path to a local folder which needs to be connected to the cloud. The tilde ‘~’ signifies the users directory of the current Windows profile, so it can be used universally for any user. It is also possible to provide an absolute filepath if necessary.

We have also introduced the ::windows_username:: tag which extracts current users Windows profile name, so that it can be used dynamically.

Special cases

There are some special cases in which the behavior of Connected folders when deployed from Configuration profile are worth noting:

 

Offline folders

This option defines which folders should be synced for offline access by default. In the example above, there are two folders synced for offline access, however, there is no lower or upper limit to how many can be synced. The number of folders can be modified by adding or removing strings configuration.

The value signifies a full file path in Egnyte cloud to a folder that should be synced. All values must be full paths e.g. “/Shared/Documents” and they must start with Cloud Start Path if it is already set. As the folder is synced to a local cache, there is no need for a local file path.

If there is a need to use a filepath specific to a user, like “Private/jsmith”, it is possible to use ::egnyte_username:: tag. Please see this section for the details. 

Available values:

String

Special cases

There are some special cases in which the behavior of Offline folders when deployed from Configuration profile are worth noting:

 

Drive Adding Restrictions

"CanAddNewDrive":  false

This option restricts users from adding their own drive configuration. When it is set to True, users will not be able to click the Add Drive button in the Desktop App interface, limiting to use preconfigured drives only.

Available values:

True

False

 

Egnyte Username Tag

The ::egnyte_username:: tag is a special placeholder used to dynamically represent an Egnyte username. As described in the Connected Folders section, this tag allows file paths to be automatically adapted to individual users without requiring manual updates for each configuration.

Dynamic Username Replacement

Whenever a file path contains the ::egnyte_username:: tag, the system replaces it with the Egnyte username of the logged-in user. This is particularly useful when deploying configurations that need to account for different users' private folders.

Example Scenario:

Consider two users, jsmith and jnewman. Their respective private folder file paths are as follows:

For jsmith:         /Private/jsmith/

For jnewman:     /Private/jnewman/

Instead of creating separate configurations for each user, the ::egnyte_username:: tag can be used to generalize the file path:

/Private/::egnyte_username::/

During runtime, the tag is dynamically replaced with the actual username, ensuring the correct file path is applied for each user.

 

Windows Username Tag

In addition to the ::egnyte_username:: tag mentioned above, there is another special tag, ::windows_username::, designed to dynamically use the current Windows user's username. This tag can be employed in file paths or configurations that need to adapt based on the logged-in user's Windows account.

How ::windows_username:: Works

Whenever a configuration includes a file path or setting with the ::windows_username:: tag, the system replaces it with the username of the currently logged-in Windows user. This allows for personalized configurations during mass deployment without requiring manual updates for individual users.

Example Use Case:

If there are two Windows users, jsmith and jnewman, and their respective local folders are to be configured dynamically, the following paths can be used:

For jsmith:          C:\Users\jsmith\Documents\

For jnewman:      C:\Users\jnewman\Documents\

With the ::windows_username:: tag, a single configuration can dynamically adapt to both users:

C:\Users\::windows_username::\Documents\

 

Exporting Configuration via CLI

Admins can use the CLI to export the current drive and folder configuration from an admin machine, making it easier to apply the same configuration across other machines.

EgnyteClient.exe  -command  managed_configuration_generate  -p  <path_to_output_file>

Configuration will be exported in JSON format.

 

Deployment Instructions

Once the configuration file is ready, it can be deployed to user machines. Below are the deployment steps:

Deploying the Configuration via Installer

1. Install the Egnyte Drive with Configuration File
   

   The installer supports a new argument ED_MASS_CONFIG_FILE_PATH, which specifies the path to the configuration file during installation.

    Example Command:

    msiexec   /i   EgnyteDrive.msi   ED_MASS_CONFIG_FILE_PATH=<path_to_config_file>

2. File Copy Process
   

   The configuration file is copied to the installation directory as defaultMassDeploymentConfig.json. During startup, the Egnyte Drive application copies this file to <ED_DATA_STORAGE_DIRECTORY>/config/massDeploymentConfig.json` and applies the provided configuration.

   <ED_DATA_STORAGE_DIRECTORY> is usually located in C:\Users\<username>\AppData\Local\Egnyte Connect\.

Deploying via Microsoft Intune

1. Prepare Deployment Files:
   Create a folder with the following:
   - `EgnyteDrive.msi`
   - Configuration file (`config.json`)
   - Installation script (`install.cmd`): 
   

   cmd

      echo off

      set "currentDir=%~dp0"

      set "configFilePath=%currentDir%config.json"

      msiexec /i EgnyteDrive.msi /quiet ED_MASS_CONFIG_FILE_PATH="%configFilePath%"

      msiexec /i EgnyteDrive.msi /L*VX  <destination path>\install.log

   
   
   
2. Convert Folder to `.intunewin`:
   Use the [Microsoft Win32 Content Prep Tool] (https://github.com/Microsoft/Microsoft-Win32-Content-Prep-Tool) to package the folder for Intune deployment.
   
   
3. Upload to Intune:
   Log into Microsoft Endpoint Manager Admin Center, Navigate to Apps > Windows > Add, and upload the `.intunewin` package. Set the install command to run the `install.cmd` script.
   
   

Deploying Manually via File Copy

1. Navigate to the config folder within the Egnyte Drive data storage directory:
   <ED_DATA_STORAGE_DIRECTORY>/config/
   

   <ED_DATA_STORAGE_DIRECTORY> is usually located in C:\Users\<username>\AppData\Local\Egnyte Connect\.

2. Place the desired configuration file(s) in the folder.
3. The name of the file must match massDeploymentConfig.json. Only one file can be deployed at a time.
4. Restart the Desktop App or run the commands mentioned in the section below. 

 

Additional CLI commands to support manual file update:

EgnyteClient.exe   -command   managed_configuration_update   -p   <path_to_source_path>

This command uses a file under the specified path as a configuration file.

EgnyteClient.exe   -command   managed_configuration_clear

This command clears all configuration files. 

 

Ready-to-use configuration

Below is a configuration file that consists only of essential settings. It sets up a Z:\ drive labeled as Egnyte. Only the Domain value needs to be changed to reflect the Egnyte domain (see below) and it is ready to use. It also has predefined Desktop and Documents folders as Connected folders, so that users always have them backed up to their Private folders. This is the most basic configuration that can be used to mass deploy Desktop App, however, some settings can be changed as needed.

Please use any XML or Text editor to edit those files. 

Example Windows Configuration

Configuration is as follows:

Part to be edited:

"Domain": "<domain>.egnyte.com"

If your domain name is acme, then replace this value with acme.egnyte.com

 

Edge Cases and Conflict Handling

When applying mass configurations, certain edge cases and conflicts may arise due to existing drive settings, folder structures, or synchronization issues. To ensure seamless operation and minimize disruption, the system incorporates mechanisms to handle these scenarios intelligently. Below is an overview of how the system resolves potential conflicts, manages pre-existing settings, and notifies users or administrators of any issues encountered during the process.

1. Conflicts with Drive Letters or Labels
   • When a drive letter or label specified in the configuration is already in use, the system will not create a new drive. The exception is when the configuration is an exact match, then it is promoted to Organisation Managed drive (See #4)
2. Pre-Existing Connected Folders
   • If a connected folder defined in the configuration already exists on the drive:
     • The folder will not be modified or replaced. Instead, it will be designated as managed by the administrator.
     • If a connected folder is deleted locally by the user, the system does not show any error messages, but the action is recorded in the log file.
3. Offline Folder Synchronization Issues
   • Predefined offline folders cannot be modified or edited by users.
   • If these folders are deleted from the cloud, synchronization will fail. Such events are captured in the system logs for the administrator to address.
4. Promotion of Drives to Organisation Managed Status
   • Drives that match specific criteria—such as the same drive letter, domain, label, and cloud path as defined in the configuration—are automatically promoted to Organisation Managed status.
   • Once promoted, these drives become non-editable by users, ensuring consistent configurations.

 

Logs and Notifications Overview

Logging System

• The system keeps detailed logs of all issues related to drives, folders, and configurations in the mass_deployment.log file, which can be found in <ED_DATA_STORAGE_DIRECTORY>\logs\
• The log entries include:
  • Conflicts involving drive letters or labels
  • Missing connected or offline folders
  • Insufficient storage space for offline synchronization

User Notifications

• Users are notified about the status of their configuration in real time:
  • Success Notification: Confirms that the configuration has been applied without issues.
  • Failure Notification: Alerts the user about conflicts or problems that prevent the configuration from being fully applied.

 

Widget indicators and restrictions

Widget indicator

When a Configuration profile is applied, there will be a visible indication of it in Desktop App Widget on Drive, Connected, and Offline folders.

Widget action restrictions

Drives specified in the Configuration will have some actions restricted, so that users cannot change the configuration. Users can add and configure new drives on their own (unless Drive Adding Restriction is applied) as well as set up any additional Connected and Offline folders.

• Drive removal and disconnect actions are restricted, preventing the removal or disconnection of an Organization managed drive. However, users can reconnect the drive if it becomes disconnected for any reason.
• Alterations to the configuration of an Organization managed drive are not permitted.
• Removal of Organization managed Offline folders is restricted.
• Organization managed Connected folders cannot be removed by users. This restriction does not extend to deleting a local folder on their Windows, which would result in a lost connection that won't be restored until the folder is recreated.

Applying and removing configuration

When applying and removing configuration, following items are worth noting:

• Once the configuration is deployed, the Desktop App needs to be restarted in order for the settings to be applied.
• If a drive with a selected drive letter already exists, but it has different configuration, it will not be overwritten and its mounting will fail. 
• If the configuration is exactly the same, then it will be marked as Managed by Organization.The same applies for Connected folders and Offline folders.
• If a configuration is removed, the drive is removed as well.

 

Troubleshooting and logs

If applying configuration or part of it fails, there is a dedicated log file to help with troubleshooting. It can be accessed in following location: 

C:\Users\<username>\AppData\Local\Egnyte Connect\logs\mass_configuration.log