Connecting a macOS Client to a Database Server

Depending on your version of macOS, connecting a macOS client to a database server can be done in one of the two following ways:

  • On macOS clients prior to macOS 10.15 (Catalina), you can do it using the traditional method, that is by creating mount points to the network shares of your database server and your scene data servers in the root of the file system, like so: /USA_DB, /usadata000, /usadata001, etc.
  • macOS clients with macOS 10.15 (Catalina) or later: Create your mount points (USA_DB, usadata000, usadata001, etc.) in /System/Volumes/Data/mnt, and then configure shortcuts.conf to indicate their location—see About the Location of Mount Points on macOS.

The main reason for the different configuration methods is that, starting from macOS 10.15 (Catalina), macOS does not allow you to create files or directories at the root folder (/) of the filesystem.

TIP If you upgraded to macOS 10.15 (Catalina) or later from an earlier version of macOS, anything you have created in the root folder (/) was automatically moved to /Users/Shared/Relocated Items.

If your client currently has an older version of macOS, but you plan to upgrade to macOS Catalina in the future, you can immediately future-proof your setup by configuring it in the way that is compatible with macOS 10.15 (Catalina) or later, as it also works on previous versions of macOS.

If your network shares use the NFS protocol, you can create mount points for them using macOS‘s autofs system.

However, if your network shares use the Samba protocol, the only known working way of mounting them automatically on log-in is to connect to these shares manually in Finder, creating symbolic links to those shares in the appropriate locations and then, if those symlinks are not in the root folder (/) of your filesystem, configuring shortcuts.conf to indicate the location of those symlinks. Note that this method has two important limitations:

  • If your client needs to run background services, those must be launched using the Service Launcher application, rather than by the services created using Harmony‘s Configuration Assistant application.
  • If several users are configured to mount those network shares, only one of these users at a time can be logged-in. This is because if two logged-in users have the same network shares mounted via Finder or log-in items, the name of the mount points for second user to log-in will be different. One macOS, a mounted Samba share can only be accessed by the user who mounted it. Therefore, on the second logged-in user’s account, Harmony will try to access the first logged-in user’s mount points and will be denied access.

  1. In a terminal, open the autofs’s main configuration file for editing:

    $ sudo vi /etc/auto_master

  2. If it doesn’t already exist, add the following line to the file:

    /- auto_nfs -nobrowse,nosuid

    This will make macOS autofs system load your NFS mount points configuration file.

  3. Save the file, then open the NFS mount points configuration file:

    $ sudo vi /etc/auto_nfs

  4. Add an entry in the following format for each network share that your Harmony database requires:

    /System/Volumes/Data/mnt/<share name> -fstype=nfs,rw,soft,intr,resvport nfs://<server name>:/<share path & name>

    For example, if your main database server is named harmonyserver and hosts the database files (USA_DB) as well as the first scene data storage space, named usadata000, and you have another scene data server called scenedataserver hosting the second scene data storage space, named usadata001, you would need to add the following lines:

    /System/Volumes/Data/mnt/USA_DB -fstype=nfs,rw,soft,intr,resvport nfs://harmonyserver:/USA_DB /System/Volumes/Data/mnt/usadata000 -fstype=nfs,rw,soft,intr,resvport nfs://harmonyserver:/usadata000 /System/Volumes/Data/mnt/usadata001 -fstype=nfs,rw,soft,intr,resvport nfs://scenedataserver:/usadata001

  5. The paths starting with /mnt/ are the folders where you will mount your network shares on your workstation, referred to as mount points. Those folders must exist on your workstation and must be empty. Hence, you must create them before you can try mounting those network shares. First, type the following command to create the /mnt directory:

    $ sudo mkdir /System/Volumes/Data/mnt

  6. Then, for each network share you have, type in the following command:

    $ sudo mkdir -m 777 /System/Volumes/Data/mnt/<share name>

  7. We will configure Harmony will to look for these shares in /System/Volumes/Data. Thus, you must create symbolic links pointing to each mount point in /System/Volumes/Data. To do this, type in the following command for each network share:

    $ sudo ln -s /System/Volumes/Data/mnt/<share name> /System/Volumes/Data/<share name>

  1. Now, to configure Harmony to look for the mountpoints in /System/Volumes/Data, we must edit its shortcuts.conf configuration file. In a terminal, enter the following command:

    $ sudo vi "/Applications/Toon Boom Harmony 20 [Edition]/Harmony [Edition].app/Contents/tba/etc/shortcuts.conf"

  2. At the top of the file, type the following header line:

    shortcut_list :

  3. Under shortcut_list :, add a line specifying the location of the mount point for each of the mounted network shares in the following format:

    /<share name> /<full path to symlink to mount point>

    In the example described above, this would result in the following:

    /USA_DB /System/Volumes/Data/USA_DB /usadata000 /System/Volumes/Data/usadata000 /usadata001 /System/Volumes/Data/usadata001

  4. Save and quit.

You should now be able to connect to your database server in Harmony. macOS will automatically attempt to mount the shares you configured as soon as any application tries to access them.

  1. In a terminal, open the autofs’s main configuration file for editing:

    $ sudo vi /etc/auto_master

  2. If it doesn’t already exist, add the following line to the file:

    /- auto_nfs -nobrowse,nosuid

    This will make macOS autofs system load your NFS mount points configuration file.

  3. Save the file, then open the NFS mount points configuration file:

    $ sudo vi /etc/auto_nfs

  4. Add an entry in the following format for each network share that your Harmony database requires:

    /mnt/<share name> -fstype=nfs,rw,soft,intr,resvport nfs://<server name>:/<share name>

    For example, if your main database server is named harmonyserver and hosts the database files (USA_DB) as well as the first scene data storage space, named usadata000, and you have another scene data server called scenedataserver hosting the second scene data storage space, named usadata001, you would need to add the following lines:

    /mnt/USA_DB -fstype=nfs,rw,soft,intr,resvport nfs://harmonyserver:/USA_DB /mnt/usadata000 -fstype=nfs,rw,soft,intr,resvport nfs://harmonyserver:/usadata000 /mnt/usadata001 -fstype=nfs,rw,soft,intr,resvport nfs://scenedataserver:/usadata001

  5. The paths starting with /mnt/ are the folders where you will mount your network shares on your workstation, referred to as mount points. Those folders must exist on your workstation and must be empty. Hence, you must create them before you can try mounting those network shares. First, type the following command to create the /mnt directory:

    $ sudo mkdir /mnt

  6. Then, for each network share you have, type in the following command:

    $ sudo mkdir -m 777 /mnt/<share name>

  7. Finally, since Harmony will be looking for those share in the root (/) directory of your filesystem, create symbolic links pointing to each mount point in /. To do this, type in the following command for each network share:

    $ sudo ln -s /mnt/<share name> /<share name>

    Once this is done, you should be able to connect to your database server using Harmony. macOS will automatically attempt to mount the shares you configured as soon as any application tries to access them.

  1. In the top menu of Finder, select Go > Connect to Server.

    The Connect to Server dialog appears.

  2. In the address field, type in the path to the share for your database files, in the following format:

    smb://<server name>/USA_DB

    For example, if your database server is named harmonyserver, you would type:

    smb://harmonyserver/USA_DB

  3. Click Connect.

  4. In the authentication dialog, select whether to connect as Guest or Registered User.

    In the latter case, type in the name and password of a user who has access to the network share and check Remember this password in my keychain to avoid having to authenticate again on every log-in.

  5. Click Connect.

    A Finder window opens and displays the content of the network share.

  6. Repeat the process for every scene data share on your network.

    For example, if you have a scene data folder with number 000 on a server named harmonyserver, and another one on a server named scenedataserver with the number 001, you would have to connect to smb://harmonyserver/usadata000 and smb://scenedataserver/usadata001 using the same steps as for USA_DB.

  7. In the top menu, open the Apple menu and select System Preferences.
  8. Open the Users & Groups panel.
  9. Click on the Login Items tab.

  10. In one of the Finder windows you opened, you can see the list of connected network shares. Click and drag each of the network shares you just connected to from Finder and drag them to your user’s list of Login Items.

    This will make macOS connect to those network shares automatically when logging in.

  11. In a terminal, run the following command for each network share, where <share name> is the name of the network share.

    $ sudo ln -s /Volumes/<share name> /<share name>

    For example, if you connected to network shares named USA_DB, usadata000 and usadata001, you would run the following commands:

    $ sudo ln -s /Volumes/USA_DB /USA_DB

    $ sudo ln -s /Volumes/usadata000 /usadata000

    $ sudo ln -s /Volumes/usadata001 /usadata001

At this point, you should be able to connect to the database server in Harmony.

NOTES

Keep in mind the following limitations to this method:

  • Login items work on a per-user basis. You must perform the steps required to add the network shares to the user’s login items for every user account that will connect to the database from the client.

  • If you need to switch from one user account to another, you must log out of the first logged-in user before switching.

    The reason for this is that if one user with these login items logs on, then a second user with the same login items logs on without the first user logging out first, the network shares for that second user will be named differently. Hence, Harmony will attempt to access the first user’s network shares, but it will not be able to access it from the second user’s account.

  • If you installed the Harmony daemons using Harmony’s Configuration assistant, they will not be able to access the Harmony database unless you are logged in as user usabatch. Hence, it is recommended to use Service Launcher to run Harmony’s background services as the logged in user instead. For information on how to do this, see Running the Database Server on Log-In on macOS, Running the WebCC Server on Log-In on macOS and Running the Batch Processing Service on Log-In on macOS.

  1. In the top menu of Finder, select Go > Connect to Server.

    The Connect to Server dialog appears.

  2. In the address field, type in the path to the share for your database files, in the following format:

    smb://<server name>/USA_DB

    For example, if your database server is named harmonyserver, you would type:

    smb://harmonyserver/USA_DB

  3. Click Connect.

  4. In the authentication dialog, select whether to connect as Guest or Registered User.

    In the latter case, type in the name and password of a user who has access to the network share and check Remember this password in my keychain to avoid having to authenticate again on every log-in.

  5. Click Connect.

    A Finder window opens and displays the content of the network share.

  6. Repeat the process for every scene data share on your network.

    For example, if you have a scene data folder with number 000 on a server named harmonyserver, and another one on a server named scenedataserver with the number 001, you would have to connect to smb://harmonyserver/usadata000 and smb://scenedataserver/usadata001 using the same steps as for USA_DB.

  7. In the top menu, open the Apple menu and select System Preferences.
  8. Open the Users & Groups panel.
  9. Click on the Login Items tab.

  10. In one of the Finder windows you opened, you can see the list of connected network shares. Click and drag each of the network shares you just connected to from Finder and drag them to your user’s list of Login Items.

    This will make macOS connect to those network shares automatically when logging in.

  11. In a terminal, run the following command for each network share, where <share name> is the name of the network share.

    $ sudo ln -s /Volumes/<share name> /<share name>

    For example, if you connected to network shares named USA_DB, usadata000 and usadata001, you would run the following commands:

    $ sudo ln -s /Volumes/USA_DB /System/Volumes/Data/USA_DB

    $ sudo ln -s /Volumes/usadata000 /System/Volumes/Data/usadata000

    $ sudo ln -s /Volumes/usadata001 /System/Volumes/Data/usadata001

  1. Now, to configure Harmony to look for the mountpoints in /System/Volumes/Data, we must edit its shortcuts.conf configuration file. In a terminal, enter the following command:

    $ sudo vi "/Applications/Toon Boom Harmony 20 [Edition]/Harmony [Edition].app/Contents/tba/etc/shortcuts.conf"

  2. At the top of the file, type the following header line:

    shortcut_list :

  3. Under shortcut_list :, add a line specifying the location of the mount point for each of the mounted network shares in the following format:

    /<share name> /<full path to symlink to mount point>

    In the example described above, this would result in the following:

    /USA_DB /System/Volumes/Data/USA_DB /usadata000 /System/Volumes/Data/usadata000 /usadata001 /System/Volumes/Data/usadata001

  4. Save and quit.

At this point, you should be able to connect to the database server in Harmony.

NOTES

Keep in mind the following limitations to this method:

  • Login items work on a per-user basis. You must perform the steps required to add the network shares to the user’s login items for every user account that will connect to the database from the client.

  • If you need to switch from one user account to another, you must log out of the first logged-in user before switching.

    The reason for this is that if one user with these login items logs on, then a second user with the same login items logs on without the first user logging out first, the network shares for that second user will be named differently. Hence, Harmony will attempt to access the first user’s network shares, but it will not be able to access it from the second user’s account.

  • If you installed the Harmony daemons using Harmony’s Configuration assistant, they will not be able to access the Harmony database unless you are logged in as user usabatch. Hence, it is recommended to use Service Launcher to run Harmony’s background services as the logged in user instead. For information on how to do this, see Running the Database Server on Log-In on macOS, Running the WebCC Server on Log-In on macOS and Running the Batch Processing Service on Log-In on macOS.