Desktop App Core Configuration Profile Support

Overview

The Egnyte Desktop App Core now supports Apple Configuration profiles. Starting with version v 0.12.0 (released on April 8, 2024), we are extending the support with new configuration options and UI modifications. In addition, these new items cannot be modified by users with drives added by configuration profiles. This will allow configurations to be maintained on a user's machine by IT Administrators.

Users can still freely add and configure new drives on their own. As well as set up any Connected Folder and Offline Access, alongside drives managed by the Organization.

Available configuration options

As a part of the configuration, various settings can be configured such as:

1. Drive label *
2. Domain *
3. Cloud Start Path
4. Username
5. SSO settings
6. Connected folders
7. Offline folders
8. Auto upgrade enable/disable
9. Egnyte as a default Office files handler

* Indicates mandatory option.

How does it work?

Prepare a Configuration profile

To deploy these settings to MacOS devices using an MDM (Mobile Device Management) you will need to prepare a configuration profile and either paste it into your MDM solution or create a “.mobileconfig” payload to push as a configuration profile.

A sample configuration with various options can be viewed below:

Sample configuration

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <dict>
            <key>PayloadContent</key>
            <dict>
                <key>com.egnyte.DesktopApp</key>
                <dict>
                    <key>Forced</key>
                    <array>
                        <dict>

                            <key>mcx_preference_settings</key>

                            <dict>

<key>ManagedDrives</key>

<array>

    <dict>

        <key>Domain</key>

        <string>desktop.egnyte.com</string>

        <key>Label</key>

        <string>Desktop</string>

        <key>UserName</key>

        <string></string>

        <key>UseSSO</key>

        <false/>

        <key>CloudStartPath</key>

        <string>/</string>

        <key>ConnectedFolders</key>

        <array>

            <dict>

                <key>CloudPath</key>

                <string>/Private/::egnyte_username::/Documents</string>

                <key>CreateChild</key>

                <false/>

                <key>LocalPath</key>

                <string>~/Documents</string>

            </dict>

            <dict>

                <key>CloudPath</key>

                <string>/Private/::egnyte_username::/Desktop</string>

                <key>CreateChild</key>

                <false/>

                <key>LocalPath</key>

                <string>~/Desktop</string>

            </dict>

        </array>

        <key>OfflineFolders</key>

        <array>

            <string>/Shared/Egnyte Templates</string>

 <string>/Private/::egnyte_username::/Drafts</string>

        </array>

    </dict>

</array>

<key>BandwidthThrottling</key>

<dict>

    <key>MaxDownloadSpeed</key>

    <integer>1024</integer>

    <key>MaxUploadSpeed</key>

    <integer>1024</integer>

</dict>

<key>AutoUpgradeEnabled</key>

<true/>

<key>DoubleClickCollaborationEnabled</key>

<true/>

<key>ExcludedFromLocking</key>

<array>

    <string>mdworker</string>

<string>Microsoft Word</string>

</array>

                            </dict>

                        </dict>

                    </array>

                </dict>

            </dict>

            <key>PayloadDescription</key>

            <string></string>

            <key>PayloadDisplayName</key>

            <string>Egnyte Desktop App</string>

            <key>PayloadEnabled</key>

            <true/>

            <key>PayloadIdentifier</key>

            <string>UUID1</string>

            <key>PayloadOrganization</key>

            <string>Egnyte</string>

            <key>PayloadType</key>

            <string>com.apple.ManagedClient.preferences</string>

            <key>PayloadUUID</key>

            <string>UUID1</string>

            <key>PayloadVersion</key>

            <integer>1</integer>

        </dict>

    </array>

    <key>PayloadDescription</key>

    <string></string>

    <key>PayloadDisplayName</key>

    <string>Egnyte Desktop App</string>

    <key>PayloadEnabled</key>

    <true/>

    <key>PayloadIdentifier</key>

    <string>UUID2</string>

    <key>PayloadOrganization</key>

    <string>Egnyte</string>

    <key>PayloadRemovalDisallowed</key>

    <false/>

    <key>PayloadScope</key>

    <string>System</string>

    <key>PayloadType</key>

    <string>Configuration</string>

    <key>PayloadUUID</key>

    <string>UUID2</string>

    <key>PayloadVersion</key>

    <integer>1</integer>

</dict>

</plist>

Domain (mandatory)

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

Available values:

• String

 <key>Domain</key>

 <string>domain.egnyte.com</string>

Label (mandatory)

This is a mandatory parameter. It signifies the label that will be used by the Mounted drive.

 <key>Label</key>

<string>Shared Drive</string>

Username

This option allows the Admin to define the username to be associated with the mounted drive. By default for mass deployment, it can be left empty,  the user will be required to input their username later on.

<key>UserName</key>

<string></string>

If the username is to be specified it should be applied as follows (this is example for username jsmith):

<key>UserName</key>

<string>jsmith</string>

SSO configuration

This setting determines if Single Sign-On (SSO) should be used for authentication. When set to true, SSO login will be enforced, and the UserName field will be ignored, as the account will be determined by the SSO provider. 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

<key>UseSSO</key>

<false/>

Cloud Start Path

This option defines the default starting path for the mounted drive. In the example, the mounted drive will display the topmost level folder(Shared and Private).

<key>CloudStartPath</key>

<string>/</string>

If the user is expected to begin from the "/Shared/Finance" folder within their drive, the code should be modified to the following:

<key>CloudStartPath</key>

<string>/Shared/Finance</string>

Available values:

• String

If there is a need to use a file path 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.

  <key>ConnectedFolders</key>
<array>
	<dict>
		<key>CloudPath</key>
		<string>/Private/::egnyte_username::/Documents</string>
		<key>CreateChild</key>
		<false/>
		<key>LocalPath</key>
		<string>~/Documents</string>
	</dict>
	<dict>
		<key>CloudPath</key>
		<string>/Private/::egnyte_username::/Desktop</string>
		<key>CreateChild</key>
		<false/>
		<key>LocalPath</key>
		<string>~/Desktop</string>
	</dict>
</array>

Each connected folder consists of the following structure:

Cloud Path

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.

<key>CloudPath</key>

<string>/Private/::egnyte_username::/Documents</string>

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

Create Child specifies if the local folder should be connected directly to the specified cloud path, or created as a subfolder. For an illustrative example, imagine you have a local folder named "Photos" that you want to sync with a cloud service.

If the "Create Child" option is set to false, the photos from your local "Photos" folder will be synced directly into an existing cloud folder named "Gallery". So, when you open the "Gallery" folder in the cloud, you'll see all your photos there, along with any other files or photos that were already in the "Gallery" folder.

Conversely, if the "Create Child" option is set to true, the system will create a new subfolder within "Gallery", named after your local folder, like "Photos". Your local "Photos" folder's contents will then be synced into this new "Gallery/Photos" subfolder. This way, when you access the "Gallery" folder in the cloud, you'll see a "Photos" subfolder separate from other files in the "Gallery".

Available values:

• true
• false

<key>CreateChild</key>

<false/>

Local Path

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

<key>LocalPath</key>

<string>~/Documents</string>

Special Cases

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

 

Scenario	Expected behavior
Local folder does not exist	Setting up Connected folders will fail
Cloud folder does not exist	Cloud folder will be created with name specified in Configuration profile and Connected folder will be set up
Cloud folder already exists	Connected folder will be set up and contents of local and cloud folders will be merged
Cloud folder already exists but user doesn’t have permissions to it	Setting up Connected folders will fail

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, but there is no lower or upper limit to how many can be connected which 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 and they must start with Cloud Start Path if it is 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. 

<key>OfflineFolders</key>

<array>

<string>/Shared/Egnyte Templates</string>

<string>/Private/::egnyte_username::/Drafts</string>

</array>

Special Cases

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

Scenario	Expected behavior
Cloud folder does not exist	Setting up an Offline folder will fail
Cloud folder already exists, but the user doesn’t have permission to edit the folder	Setting up an Offline folder will fail
Offline folders are disabled in WebUI	Setting up an Offline folder will fail
Insufficient disk space	Offline folder will be set up, but the sync will be paused

Bandwidth Throttling

Configures maximum download and upload speed for Connected folders and Offline folders. This setting can be useful if users rely heavily on Connected folders and Offline folders and don’t want to overuse their bandwidth.

Available values:

Integer expressed in KB/s. Value must be set to at least 25 KB

<key>BandwidthThrottling</key>

<dict>

    <key>MaxDownloadSpeed</key>

    <integer>1024</integer>

    <key>MaxUploadSpeed</key>

    <integer>1024</integer>

</dict>

Auto-upgrade Enabled

Configures if the Desktop App should update automatically when a new version is available. This value overrides default autoupgrade settings configured for the domain in the Admin panel.

Available values:

• true
• false

 <key>AutoUpgradeEnabled</key>

<true/>

Co-edit on Double Click

This setting controls if Egnyte is set as a default handler for Office applications. It should be set to true if Co-edit functionality is enabled, otherwise it will not be available on double click. The value should be set to false only in cases where there are conflicts with 3rd party software which cannot be otherwise resolved.

Available values:

• true (Default)
• false

<key>DoubleClickCollaborationEnabled</key>

<true/>

Exclude Process from Locking Files

This option defines the process name for applications that will not be locking files. In this example any file opened by mdworker process will not be locked and other users will be able to access it.

Please note that any changes made and saved to those files will result in a Conflict copy of the file.

Available values:

String

<key>ExcludedFromLocking</key>

<array>

  <string>mdworker</string>

<array/>

Egnyte Username Tag

As mentioned in Connected folders section, there is a special ::egnyte_username:: tag that signifies dynamic Egnyte username. Any time when there is a filepath that includes Egnyte username that need to be dynamically changed for different users, this tag can be used. 

For instance, if there are two users - jsmith and jnewman, their respective Private folder filepaths will be:
/Private/jsmith/

/Private/jnewman/

For mass deployment purposes it is possible to use ::egnyte_username:: tag to dynamically replace it:

/Private/::egnyte_username::/

Ready-to-use Configuration

Below is the configuration file that consists only of essential settings. It sets up a drive for the user that is labeled as Egnyte. Only the Domain value needs to be changed to reflect your 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 directories. This is the most basic configuration you can use to mass deploy your Desktop App Core, however, some settings can be changed as needed.

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

Basic XML file

Full .mobileconfig file 

Part to be edited:

 <key>Domain</key>

<string>yourdomain.egnyte.com</string>

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

 

Widget indicators and restrictions

Widget Indicator

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

Widget action restrictions

Drives specified in the Configuration profile will have some actions restricted, so that users cannot change the configuration. Users can add and configure new drives on their own 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 Mac, 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, Desktop App Core needs to be restarted in order for the settings to be applied.
• If a drive with a selected label 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 Offine folders.
• If a configuration is removed, the drive is removed as well.

Troubleshooting and Logs

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

~Library/Group Containers/FELUD555VC.group.com.egnyte.DesktopApp/Logs/ManagedConfiguration.log