Installing CrossOver on Multiple Systems

CrossOver provides several ways to roll out Windows applications to a large number of users and on a large number of systems. The most basic of these tools is bottle publication, which allows all the users of a single system to share a single installation of each application.

To install CrossOver on multiple stand-alone systems, we have provided the ability to create an RPM, Debian, or Solaris package from a bottle<!-- where is this supposed to link to? -->. Or, if you use NFS or Samba to share drives in your network, you can install using a shared volume.

Creating an RPM, Debian, or Solaris package from a bottle

CrossOver can create an installable package out of a bottle. This service allows you to create a bottle on one system, package it up, and reinstall it on many additional machines. The resulting packages must be installed with a corresponding CrossOver program package.

The package creation feature is available on the Advanced tab in the Bottle Manager.

Alternatively you can create the packages from the command-line. For instance the following command will create Debian and RPM packages for the <bottle-name> bottle:

    $ @DOC_USERPREFIXDIR@/bin/cxbottle --bottle bottle-name --deb --rpm


Although you can create a package out of any bottle (published or private), the bottle will be installed on any new system as though the bottle had been published on that system.


To create Debian or RPM packages, you will need your Linux distribution's corresponding packaging tools.

Once the bottle package installation completes, the applications it contains are ready to go. Make sure you have purchased a CrossOver license for each system you're using, and be careful to comply with all of the license terms for each Windows program. CrossOver does not enforce software licensing restrictions.

Installing onto a shared volume

CrossOver may be installed on a shared volume and run on multiple systems. First, make sure that files created by root on the shared volume will belong to root. For instance:

    # touch /common/software/root-file
    # ls -l /common/software/root-file
    -rw-r--r--  1 root root 0 Nov  4 14:07 /common/software/root-file

This should show that root-file belongs to root. Once this works, delete root-file and install CrossOver, specifying the shared drive as the install location.

If you are happy to run applications using the command line, then you're done. However, if you would like menus and associations to be available on your users' machines, then there are a few more steps.

Creating the CrossOver menus

To create the CrossOver menu entries, run the following cxmenu command as root on each system.

    # /common/software/@DOC_PREFIXDIR@/bin/cxmenu --ro-desktopdata --crossover --install

Setting up the Windows executable association

Associating the .exe extension with CrossOver lets users launch Windows executables (like notepad) by clicking on them in their file browsers. To enable it, run this command as root on each system:

    # /common/software/@DOC_PREFIXDIR@/bin/cxassoc --ro-desktopdata --crossover --install

Setting up the .tie association

To associate the .tie extension with CrossOver so that users can install Windows applications using CrossTie profiles, run this command on each system:

    # /common/software/@DOC_PREFIXDIR@/bin/cxtie --register

Creating menus, associations, and plugin links for Windows applications

With private multi-user installs, each user will have their own Windows menus, associations, and plugins.

In order to recreate the menus and associations of a published bottle, run the cxbottle command as root on each system, like this:

    # /common/software/@DOC_PREFIXDIR@/bin/cxbottle --ro-desktopdata --bottle bottle-name --install

Where <bottle-name> is the name of your published bottle. If you have more than one published bottle on your shared drive, repeat the above
command for each.

Side-by-side installations

Should the need arise, it is possible to install two or more versions of CrossOver side-by-side, so they don't interfere. When this happens, each installation tags its resources with a 'product id,' so it knows which desktop menus and associations belong to it.

When using the graphical installer, all you need to do is pick a new installation directory. The installer will then notify you that another version of CrossOver is already installed elsewhere, and if you proceed, it will automatically pick a new product id to avoid interference.


When upgrading a side-by-side configuration using the graphical installer, always double-check the installation directory to ensure you are upgrading the CrossOver instance you intended.

It is also possible to set up side-by-side configurations using Debian or RPM packages. But to do so, you must first repackage CrossOver to change the package name and the product id.

To do so, you must first install the CrossOver version to repackage. You would typically do this in a user account using the graphical installer as this avoids interference with already installed packages. Then run the following command in that account:

    $ @DOC_USERPREFIXDIR@/bin/cxrepackage --deb --productid cxnew --release 2

Where <cxnew> is both the new package name and the new product id, and <2> lets you keep track of the revisions of the new packages you create. To generate an RPM package instead of a Debian one, simply replace <--deb> with <--rpm>.


To create Debian or RPM packages, you will need your Linux distribution's corresponding packaging tools.

The new package can be installed and deployed normally next to the regular CrossOver package. You can also use it to create bottle packages that will work together with your new package instead of the regular ones.

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 that 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, registry settings, the contents of the C: drive, etc. This mechanism is beneficial when you want to customize a bottle that you distribute to a range of machines or to customize a published bottle
for each specific user.

There are three levels of Bottle hooks:

  • 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
    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 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 each
    non-root user. This is also the only kind of hook that is
    automatically packaged with the bottle when archived and is
    thus guaranteed to run when the bottle is restored later, even if
    it 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 hook's name must in 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 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 the 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> 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:"

Setting the bottle search path

One quick way to move bottles to a non-default location and have CrossOver still find them is to first create a bottle in CrossOver, move the bottle to the new location, and then create a symbolic link in the @DOC_USERBOTTLEDIR@ directory, which points to the bottle's new

You can also control the list of directories where CrossOver looks for bottles by setting the CX_BOTTLE_PATH environment variable. By default, this variable is set to @DOC_USERBOTTLEDIR@. To not have to set the modified path manually each time you run CrossOver, edit @DOC_USERCONFDIR@/@PRODUCT_ID@.conf and add the following lines:


CrossOver will then first look for bottles in /extra/bottles and then in the standard location. Also note that CrossOver will create new bottles in the first writable directory present in the search path. So the order is important.

Furthermore, CrossOver will not move existing bottles to the new location. So you need to either keep the default bottle location in the list or to move your existing bottles manually. A simple move command should do the trick:

    $ mv "@DOC_USERBOTTLEDIR@/bottle-name" /extra/bottles

If you installed CrossOver globally, you may want this setting to affect all users. To do so, you would set it in the global configuration file, that is in @DOC_SYSCONFDIR@/@PRODUCT_ID@.conf. You should also make sure each user gets their own bottle directory. Usually, you would do so by using the USER environment variable like so:


Similarly, when you publish a bottle, it is normally put in @DOC_SYSBOTTLEDIR@. However, you can change this by setting the CX_MANAGED_BOTTLE_PATH environment variable, for instance, by adding the following lines to @DOC_SYSCONFDIR@/@PRODUCT_ID@.conf:


Note that this time we've put this setting in the global configuration file, so it is accessible by all users. Also, as for CX_BOTTLE_PATH, new bottles will be placed in the first writable directory, and existing bottles will not be moved around.

Last modified on 2022-07-08 07:46:18 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/linux/linuxtutorial/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...