Advanced Manual Configuration

Most users will not need to use the instructions in this chapter. You should not attempt any of these procedures unless you have passing knowledge of the macOS command-line -- most of these sections require text commands to be issued.

Installing CrossOver on multiple systems

CrossOver supports rolling out Windows applications to a large number of users and on a large number of systems. The basic technique is bottle publication which allows all the users of a single system to share a single installation of each application. Bottle publication is simple -- just create a bottle with the included files and applications that you wish to distribute, remove any private data (for example, cached passwords and user names), and click the Publish button. After publication, all users on that system will have access to the software within the published bottle.

When a user accesses a published bottle, a 'stub bottle' will be created in their home account. Stub bottles contain a user's custom alterations to the bottle, and contain symbolic links that refer to most large files and directories in the published bottle. A stub bottle has the same name as the published bottle to which it refers.

Distributing a published bottle

The simplest way to distribute a published bottle to another Mac is to copy it into the same location on the new system (it's typically located in @DOC_SYSBOTTLEDIR@). Users on that system only need to run CrossOver once after the bottle has been added, at which point CrossOver will create any icons that are a part of that bottle.

Depending on your needs and network configuration, you may wish to provide some or all of the following customizations before pushing packages out to the target machines.

Distributing ready-made icons

If you have a facility to automatically push icons onto users' docks, you may wish to include one or more icons created by CrossOver in your distribution package. An icon will still work if copied from one machine to another, as long as the bottle path is the same on both. As soon as CrossOver is launched via the icon, it will review the icon file and may replace it with an equivalent system-local icon if appropriate.


After publishing a bottle, you will have two sets of icons, one of which refers to your private bottle, and one of which refers to the published bottle. Make sure you distribute the icons that refers to the published bottle.

Providing custom or ready-made preference files

Many sysadmins will want to modify some of CrossOver's default behavior before rolling it out widely. This can be done either by running scripted commands in each user account, or by preparing a ready-made defaults file (Typically
~/Library/Preferences/com.codeweavers.@PRODUCT_ID@.plist) and copying that file into the Preferences directory of each user account.

A few of the most useful default settings are:

Changing where a user's bottles are located

The default user bottle directory is @DOC_USERBOTTLEDIR@. Even when using published bottles this directory is used to store user-local settings. The location of this directory can be changed via the BottleDir preference:

    $ defaults write com.codeweavers.@PRODUCT_ID@ BottleDir /path/to/user_private/non_networked/bottle/dir

It is very important that you not point this setting to a directory that contains the published bottles themselves, as user settings will conflict with the system settings.

Using a networked or remote volume for the bottle directory may result in serious performance problems and is generally a bad idea.

Changing where CrossOver looks for published bottles

If you want to store the published bottles on an external volume, or on one that's shared between multiple systems, you will probably need to redirect CrossOver to look in an alternative directory. This can be accomplished using the ManagedBottleDirs preference:

    $ defaults write com.codeweavers.@PRODUCT_ID@ ManagedBottleDirs /path/to/shared/non_networked/bottle/dir

<!-- Unclear to me if the following is applicable to both unix and mac... including here in case -->

Adding a new drive or customizing the drive label / serial number

CrossOver allows you to add new drives to be used by Windows applications, and to change their label or serial number. If you need to create a new drive or have an application which depends on a serial number or Windows volume label then follow the examples below.

For example to make the path /mnt available as the drive <J:> in a bottle, you would execute the following command:

    $ ln -s /mnt "@DOC_USERBOTTLEDIR@/bottle-name/dosdevices/j:"

To associate this drive to the /dev/sda1 device you would add a double colon to the command.

    $ ln -s /dev/sda1 "@DOC_USERBOTTLEDIR@/bottle-name/dosdevices/j::"

For 'real' devices, CrossOver should automatically get the serial number and label for a volume. However you can also set these manually. To set the serial number of a given mount point you need to create a file called .windows-serial on the root of the virtual drive.

    $ echo '12345678' >/mnt/.windows-serial

To set the label you would create a file called .windows-label on the root of the virtual drive.

    $ echo 'MY_LABEL' >/mnt/.windows-label

Customizing bottles using bottle hooks

Bottle hooks are a mechanism that lets you automatically customize the bottles created by CrossOver. Because it relies on scripts, it is very flexible. For instance it can modify drive letter assignments but also registry settings, the contents of the C: drive, etc. This mechanism is especially useful when you want to customize a bottle which you distribute to a range of machines, or to customize a published bottle
for each specific user.

Bottle hooks can be created at three levels:

  • System-wide hooks apply to all bottles on the system, including
    non-root user bottles. Thus they are ideal to adapt the bottles to
    the configuration or hardware of the machine. These hooks are
    located in the $CX_ROOT/support/scripts.d directory.

  • User hooks are the same as system-wide hooks but apply only to one
    specific user's bottles. They are run after all the system-wide
    hooks have been run. They are located in the
    @DOC_USERCONFDIR@/scripts.d directory.

  • Finally, each bottle can have its own set of hooks. These are
    especially suited to configure a published bottle for use by each
    non-root user. This is also the only kind of hook which is
    automatically packaged with the bottle when it is archived, and is
    thus guaranteed to run when the bottle is restored later, even if
    this is on another computer. These hooks are located in the
    scripts.d directory in the bottle.

Each hook is an executable file, usually a shell script, and must be placed in one of the above hook directories. The name of the hook must be of the form, where nn are two decimal digits that dictate the order in which the hooks are run, and name must not contain any dot or tilde and usually indicates the hook's purpose.

The hooks are then called as described in the following events:

When a bottle is created

<hook> create <template>

The <template> parameter indicates the name of the template the bottle is based on, for instance '<win98>'.

When a bottle is restored

<hook> restore

When a bottle is upgraded to a new CrossOver version

<hook> upgrade-from <old-bottle-version>

Where <old-bottle-version> is the CrossOver version the bottle was last used with. This can help you gauge how out of date the bottle was, but note that the hooks are called only after CrossOver has upgraded the bottle.

Before and after a bottle stub is created

<hook> pre-create-stub <published-wineprefix>

<hook> create-stub <published-wineprefix>

This case happens when a published bottle is used in a non-root account for the first time. In this case the $WINEPREFIX environment variable points to the freshly created bottle stub, while <published-wineprefix> points to root's reference copy in

Before and after a bottle stub gets updated

<hook> pre-update-stub <published-wineprefix>

<hook> update-stub <published-wineprefix>

This case happens when the administrator has updated the published bottle's reference copy in <published-wineprefix> and the user's bottle stub must not be updated to match.

In all cases the hooks are called in the Wine context. This means they don't need to use the --bottle option and that they can count on the following environment variables being set:

CX_ROOT Contains the absolute path to the directory where CrossOver is

CX_BOTTLE Contains the name of the current bottle.

WINEPREFIX Contains the absolute path to the bottle directory.

Bottle hooks can also use the wine script to call WineLib or Windows applications to modify registry settings or other aspects of the bottle.

Here is an example of a bottle hook that modifies the drive letter assignments so that there is no Y: drive, and the H: drive points to the user's $HOME directory.

    rm "$WINEPREFIX/dosdevices/y:"
    if [ ! -d "$WINEPREFIX/dosdevices/h:" ]
        ln -s -f "$HOME" "$WINEPREFIX/dosdevices/h:"
Last modified on 2022-07-08 07:32:01 by CJ Silver
Are you sure you want to delete this page?
Note: Any nested pages that are under this one will be moved up one level. Any attachments tied to this page will be deleted.
Move / Rename Page
Unknown Error, unable to move!
That page exists already!
One or more of the parent pages specified in new path do not exist!
/support/wiki/ /support/wiki/mac/mactutorial/advconfig
CodeWeavers or its third-party tools process personal data (e.g. browsing data or IP addresses) and use cookies or other identifiers, which are necessary for its functioning and required to achieve the purposes illustrated in our Privacy Policy. You accept the use of cookies or other identifiers by clicking the Acknowledge button.
Please Wait...