Toon Boom
Harmony22
Installation Guide

TOON BOOM ANIMATION INC.

+1 514 278 8666

4200 St.Laurent Blvd, Suite 1020
Montreal, Quebec, Canada
H2W 2R2

contact@toonboom.com
toonboom.com

Harmony 22 Installation Guide

Legal Notices
Toon Boom Animation Inc.
4200 Saint-Laurent, Suite 1020
Montreal, Quebec, Canada
H2W 2R2
Tel: +1 514 278 8666
Fax: +1 514 278 2666
toonboom.com

Disclaimer
The content of this document is the property of Toon Boom Animation Inc. and is copyrighted. Any
reproduction in w hole or in part is strictly prohibited.
The content of this document is covered by a specific limited w arranty and exclusions and limit of liability
under the applicable License Agreement as supplemented by the special terms and conditions for
Adobe® Flash® File Format (SW F). For details, refer to the License Agreement and to those special terms andconditions.

Trademarks
Toon Boom® is a registered trademark. Harmony™ and the Toon Boom logo are trademarks of Toon Boom
Animation Inc. All other trademarks of the property of their respective ow ners.

Publication Date
09-23-2022
Copyright © 2022 Toon Boom Animation Inc., a Corus Entertainment Inc. company. All rights reserved.

1

Table of Contents

Table of Contents
Table of Contents

2

Introduction

10

Chapter 1: Basic Installation

12

About W indow s Installation

13

Installing Harmony Dependencies on W indow s

14

Installing Harmony on W indow s

16Adding Harmony Executables to the %PATH% Environment Variable on W indow s

18

About macOS Installation

19

Installing Harmony on macOS20

Launching Harmony and Side Applications on macOS

21

Adding Harmony Binaries to the $PATH Environment Variable on macOS

22

About GNU/Linux Installation

23

About GNU/Linux Installation

24

Installing Harmony Dependencies on GNU/Linux

25

Installing Proprietary Video Drivers on GNU/Linux

26

Installing Harmony on GNU/Linux

30

Adding Harmony Binaries to the $PATH Environment Variable on GNU/Linux

38

About Audio Transcoding on GNU/Linux

39

Preventing the Alt Key Keyboard Shortcut Conflict Betw een Harmony and the GNU/Linux Desktop

40

Troubleshooting Problems w ith Harmony on GNU/Linux

41

Troubleshooting a Crash W hen Loading Harmony on GNU/Linux

42

Troubleshooting Desktop Shortcuts Launching the W rong Version of Harmony

44

Chapter 2: Harmony Server

46

About the Harmony Server Structure

47

About Database Server Installation

49

Database Server Installation on W indow s

50

Disabling the Firew all for a Harmony Database Server on W indow s

51

Setting up the Database Server on W indow s

52

Removing the Scene Data Storage from the Database Server on W indow s

54

2

Harmony 22 Installation Guide

Running the Database Server Service on Log-In on W indow s

55

Opening the Firew all Ports for a Harmony Database Server on W indow s

57

Creating a Scene Data Storage Space on W indow s

59

Configuring a W indow s Database Server to have a Static IP Address

65

Looking Up the Database Server Log on W indow s

69

Launching the Database Server Manually on W indow s

70

How to Stop and Restart the Database Server on W indow s

71

Pausing and Resuming the Database Server on W indow s

73

Uninstalling the Database Server on W indow s

74

Database Server Installation on macOS

76

Setting the Server Hostname on macOS

77

Creating a Harmony Database on macOS78

Installing the Database Server Daemon on macOS

81

Running the Database Server on Log-In on macOS

83

Sharing the Harmony Database Files Using NFS on macOS85

About Supporting W indow s Clients for macOS Servers

87

Installing the Link Server Daemon on macOS

88

Running the Link Server on Log-In on macOS

89

Sharing the Harmony Database Files Using Samba on macOS

91

Configuring a macOS Database Server for W indow s Clients98

Creating a Scene Data Storage Server on macOS100

Configuring a macOS Database Server to have a Static IP Address

105

Looking Up the Database Server Log on macOS108

Launching the Database Server Manually in macOS110

Stopping and Restarting the Database Server on macOS111

Pausing and Resuming the Database Server on macOS

113

Uninstalling the Database Server on macOS114

Database Server Installation on GNU/Linux

116

Disabling Security for a Harmony Database Server on GNU/Linux

117

Creating a Harmony Database on GNU/Linux

119

3

Table of Contents

Installing the Database Server Daemon on GNU/Linux

120

Running the Database Server on Log-In on GNU/Linux122

Expanding the File Descriptor Limit for a Database Server on GNU/Linux

124

Opening the Firew all Ports for a Harmony Database Server on GNU/Linux

125

Sharing the Harmony Database Files Using NFS on GNU/Linux

126

About Supporting W indow s Clients for GNU/Linux Servers

129

Installing the Link Server Daemon on GNU/Linux

130

Running the Link Server on Log-In on GNU/Linux

132

Opening the Firew all Ports for the Link Server on GNU/Linux

134

Sharing the Harmony Database Files Using Samba on GNU/Linux

135

Opening the Firew all Ports and Configuring SELinux for a Samba Server on GNU/Linux

138

Configuring a GNU/Linux Database Server for W indow s Clients

140

Creating a Scene Data Storage Server on GNU/Linux

142

Setting Up Static IPs for W ebCC on GNU/Linux146

Checking the Database Server Log on GNU/Linux150

Launching the Database Server Manually in GNU/Linux

152

Stopping and Restarting the Database Server on GNU/Linux

153

Pausing and Resuming the Database Server on GNU/Linux

155

Uninstalling the Database Server on GNU/Linux

156

Connecting Client W orkstations to a Harmony Database Server
Configuring Harmony Server Clients on W indow s

158
159

Connecting a W indow s Client to a Database Server Using Configuration W izard

160

Manually Configuring a W indow s Client to Connect to a Harmony Database

161

Configuring the Hosts File for a W indow s Client

164

About Connecting to a Harmony Database W ithout Using Shortcut Files on W indow s

165

Configuring the Shortcuts File on W indow s

166

Setting a Custom Location for the Shortcuts Configuration File on W indow s

168

Troubleshooting Client Connections on W indow s
Configuring Harmony Server Clients on macOS

170
174

Connecting a macOS Client to a Database Server

4175Harmony 22 Installation Guide

Setting the User File Creation Permission Mask on macOS

183

Configuring the Hosts File for a macOS Client

184

About the Location of Mount Points on macOS

185

Configuring the Shortcuts File on macOS

186

Setting a Custom Location for the Shortcuts Configuration File on macOS

187

Configuring Harmony Server Clients on GNU/Linux

188

Connecting a GNU/Linux Client to a Database Server

189

Setting the User File Creation Permission Mask on macOS

191

Configuring the Hosts File for a GNU/Linux Client

193

About the Location of Mount Points on GNU/Linux

194

Configuring the Shortcuts File on GNU/Linux

195

Setting a Custom Location for the Shortcuts Configuration File on GNU/Linux

196

Harmony Server Configuration

198

Using Unicode Characters in Harmony

199

Enabling Unicode Characters in Environment, Job and Scene Names

200

Enabling Unicode in Layer/Node Names

201

Configuring Scene Resolution Presets for aHarmony Database202

Configuring Resolution Presets for Environments or Jobs

204

About Resolution Presets in XML Format

205

Chapter 3: W ebCC

208

W ebCC Server Installation

209

Installing W ebCC on W indow s

210

Disabling the Firew all for a W ebCC Server on W indow s

211

Installing the W ebCC Service on W indow s

212

Running the Database Server Service on Log-In on W indow s

213

Configuring W ebCC w ith Custom Parameters on W indow s

215

About SSL, HTTPS and W ebCC on W indow s

220

Configuring W ebCC to Use SSL on W indow s

221

Setting Up Static IPs for W ebCC on W indow s

225

Opening the Firew all Ports for a Harmony W ebCC Server on W indow s

229

5Table of Contents

Checking the W ebCC Server Log on W indow s

231

Launching the W ebCC Server Manually on W indow s

232

Stopping and Restarting the W ebCC Server on W indow s

233

Uninstalling the W ebCC Server on W indow s

235

Installing W ebCC on macOS

237

Installing the W ebCC Server Daemon on macOS

238

Running the W ebCC Server on Log-In on macOS

240

Configuring W ebCC w ith Custom Parameters on macOS

242

About SSL, HTTPS and W ebCC on macOS

247

Configuring W ebCC for SSL Support on macOS

248

Configuring a macOS W ebCC Server to have a Static IP Address

252

Looking Up the W ebCCServer Log on macOS255

Launching the W ebCC Server Manually on macOS256

Stopping and Restarting the W ebCC Server on macOS

257

Uninstalling the W ebCC Server on macOS

258

Installing W ebCC on GNU/Linux

259

Disabling Security for a W ebCC Server on GNU/Linux

260

Installing W ebCC on GNU/Linux

262

Running the W ebCC Server on Log-In on GNU/Linux264

Configuring W ebCC w ith Custom Parameters on GNU/Linux

266

About SSL, HTTPS and W ebCC on GNU/Linux

271

Configuring W ebCC for SSL Support on GNU/Linux

272

Setting Up Static IPs for W ebCC on GNU/Linux

276

Opening the Firew all Ports for a W ebCC Server on GNU/Linux280

Checking the W ebCC Server Log on GNU/Linux281

Launching the W ebCC Server Manually on GNU/Linux

282

Stopping and Restarting the W ebCC Server on GNU/Linux

283

Uninstalling the W ebCC Server on GNU/Linux

284

Configuring Render Nodes for W ebCC Servers

285

Installing the Cisco OpenH264 Codec for W ebCC on W indow s

6286

Harmony 22 Installation Guide

Installing the Cisco OpenH264 Codec for W ebCC on macOS

287

Installing the Cisco OpenH264 Codec for W ebCC on GNU/Linux

288

Configuring Local W ebCC Clients

290

Configuring a GNU/Linux W orkstation to Open Harmony Scenes from W ebCC
Configuring Remote W ebCC Clients

291
292

Disabling SSL Certificate Validation for W ebCC in Harmony
Chapter 4: Batch Processing

293
294

Creating machine-list Files

296

Batch Processing Installation

297

Installing the Batch Processing Service on W indow s

298

Installing the Batch Processing Service on W indow s

299

Running the Batch Processing Service on Log-In on W indow s

300

Looking Up the Batch Processing Log on W indow s

302

Launching Batch Processing Manually on W indow s

303

Stopping and Restarting the Batch Processing Service on W indow s

304

Interrupting a Batch Processing Task on W indow s

306

Uninstalling the Batch Processing Service on W indow s

307

Installing the Batch Processing Service on macOS

309

Installing the Batch Processing Daemon on macOS

310

Running the Batch Processing Service on Log-In on macOS

312

Looking Up the Batch Processing Log on macOS

314

Launching Batch Processing Manually on macOS315

Stopping and Restarting the Batch Processing Daemon on macOS

316

Interrupting a Batch Processing Task on macOS

317

Uninstalling the Batch Processing Daemon on macOS

319

Installing the Batch Processing Service on GNU/Linux320

Installing the Batch Processing Daemon on GNU/Linux

321

Running the Batch Processing Service on Log-In on GNU/Linux323

Checking the Batch Processing Log on GNU/Linux

325

Launching Batch Processing Manually on GNU/Linux

326

7

Table of Contents

Stopping and Restarting the Batch Processing Daemon on GNU/Linux

327

Interrupting a Batch Processing Task on GNU/Linux

328

Uninstalling the Batch Processing Daemon on GNU/Linux

329

Setting Up Default Schedules

330

Testing Batch Processing

332

Vectorization of Scanned Draw ings

333

Manually Vectorizing Scenes or Elements

334

View ing Draw ing Vectorization Lists

335

Modifying Vectorize Queue Entries

337

Rendering Scenes

338

View ing Render Queues

339

Modifying Render Queue Entries

341

Batch Processing Schedules

342

Displaying the Schedule Status

344

Reading the Schedule Status List

346

About Default Schedules

348

Displaying Default Schedules

349

Reading Default Schedule Status Lists

351

Modifying Default Schedules

353

About Periodic Schedules

356

Displaying Periodic Schedules

357

Setting Periodic Schedules

359

Clearing Periodic Schedules

363

About Supervisory Schedules

364

Displaying Supervisory Schedules

365

Setting Supervisory Schedules

367

Clearing Supervisory Schedules

371

About Environment Shut Dow n

372

Shutting Dow n Environments

373

Starting Up Environments

375

8

Harmony 22 Installation Guide

Harmony Scheduling Utilities

377

Chapter 5: Service Launcher

378

Service Launcher Top Menu

379

Service Launcher Preferences Tab

380

Service Launcher ToonBoom Process Tab

381

Service Launcher Database Server Tab

383

Service Launcher W ebCC Tab

385

Service Launcher Link Tab

387

9Introduction

Introduction
Harmony is a complex and full-featured animation suite that is designed for both small and large scale
productions. In order to respond to the different needs of studios, Harmony is not only able to run as a standalone application, but also as a production server, a w eb server and a render farm. This guide goes through all
the required steps to install and configure Harmony for all usage scenarios and on all supported platforms.

10Harmony 22 Installation Guide

11

Chapter 1: Basic Installation

Chapter 1: Basic Installation
The follow ing section explains how to install Toon Boom Harmony on a w orkstation. If you intend to use
Harmony as a stand-alone application, this is the only section of the installation guide that you need. If you
intend to use Harmony w ith a database server, you w ill need to refer to this section for installing theapplication package on your Harmony database server and its client w orkstations.

12Harmony 22 Installation Guide

About W indows Installation
Installing Harmony on W indow s is a straightforw ard process consisting mostly of running the installation
w izard, then activating the product.
Installing Harmony Dependencies on W indows

14

Installing Harmony on W indows

16

Adding Harmony Executables to the %PATH% Environment Variable on W indows

18

13

Chapter 1: Basic Installation

Installing Harmony Dependencies on W indows
On W indow s, some features of Harmony rely on the follow ing softw are:l

W indows Media Player must be installed to enable Harmony's audio and video transcoding
capabilities. On most consumer versions of W indow s, it is installed by default and only specific editionsof W indow s do not have it.

NOTE
W indow s Media Player is not supported on W indow s 7 Starter and W indow s 7 Home
Basic.

l

QuickTime Player allow s Harmony to export movie files in various video and audio codecs supportedby the QuickTime Movie (.mov) format. W ithout QuickTime Player, Harmony can still export QuickTime
Movie (.mov) files, but only w ith the H.264 (AVC) video codec and w ith uncompressed (PCM) audio.

NOTE
Harmony does not require QuickTime Player to launch and none of its other functionalities
require it.

lAdobe Reader is required on W indow s 7 and W indow s 8.1 in order to read PDF documents. It can also
be installed on W indow s 10, but W indow s 10 is bundled w ith Microsoft Edge, w hich can be used toread PDF files.

How to install Adobe Reader
1. To install Adobe Reader, follow the instructions are the follow ing address:
adobe.com/support/dow nloads/pc

How to install QuickTime Player
1. To install QuickTime Player, dow nload and run the installer from the follow ing address:
apple.com/quicktime/dow nload/pc

14

Harmony 22 Installation Guide

How to install W indows Media Player
1. W indow s Media Player is pre-installed on most versions of W indow s, but may be disabled. Follow
these steps to make sure it is enabled.
a. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories >System Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list,
select W indows System > Control Panel.

b. From the Control Panel, go to Programs > Turn W indows features on or off.
c. In the list of W indow s features, find and expand the Media Features option. W indows
Media Player should listed under Media Features. If either of these options are not listed,
see below .
d. Ensure both the Media Features and W indow s Media Player check boxes are checked.
e. Click OK.
f. W ait for the installation to finish.
g. Restart W indow s.
2. If Media Features or W indow s Media Player is not listed in the available features, make sure youredition of W indow s supports it. If it does, it may be added by installing the Media Feature Pack for
W indow s. To do this, click on the link corresponding to your version of W indow s and follow the
instructions:lMedia Feature Pack for W indows 7:
https://w w w .microsoft.com/dow nload/details.aspx?id=16546

lMedia Feature Pack for W indows 8:
https://w w w .microsoft.com/dow nload/details.aspx?id=30685

lMedia Feature Pack for W indows 10:
https://w w w .microsoft.com/dow nload/details.aspx?id=48231

15

Chapter 1: Basic Installation

Installing Harmony on W indows
You can install Harmony on W indow s by running the installation w izard. Once the installation process isfinished, you w ill need to activate Harmony before you can use it.

NOTE
You need an account w ith administrator privileges to launch the installer.

How to install Harmony on W indows
1. In a file brow ser, double-click on the installer package you have dow nloaded.
2. W hen prompted by W indow s, give the permission to the installer to make changes to your device.

NOTE
If you are not currently logged in w ith an administrator account, you w ill need toprovide the username and passw ord of an account w ith administrator privileges.

3. In the Choose Setup Language prompt, select the preferred language for the installation process
and for reading the end-user license agreement.
4. W ait for the installer to prepare the installation.
5. In the w elcome screen, click on Next.
6. If you accept the license agreement presented in the installation w izard, select I accept the terms
in the license agreement, then click on Next. Otherw ise, click on Cancel.
7. If you w ant to install Harmony in the default installation directory, select Next. Otherw ise, click on
Change and select a preferred installation directory.
8. In the Installation Type dialog, select the appropriate package type:l

If you intend to w ork in a Harmony Server environment, w hether as server or as a client
w orkstation, select Complete.

l

If you only intend to w ork in a fully standalone environment or if you only intend to connect
to a Harmony database using W ebCC only, select Standalone.

9. Click on Install.
10. W ait for the installation process to finish. Once the process is finished, you are ready to launch theapplication.
11. Open the W indow s Start menu.
12. In the Programs list, select Harmony 22 [Edition] > Harmony [Edition].

16

Harmony 22 Installation Guide

13. If your product is not activated, the Toon Boom Activation W izard w ill launch. For information on
how to activate Harmony, see the Toon Boom License Activation Documentation at the follow ing
address:
https://docs.toonboom.com/help/activation

17

Chapter 1: Basic Installation

Adding Harmony Executables to the %PATH% Environment Variable
on W indows
You can add the path to the Harmony executable files to the %PATH% environment variable. This w ill allow you
to run Harmony and its applications and utilities from the command line by typing the name of the executable
files, w ithout having to type their full path.

NOTE
You need an account w ith administrator privileges to do this.

How to add Harmony executables to the %PATH% environment variable on
W indows
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
3. In the Toon Boom Harmony Configuration dialog, select the ... button right of Add Harmony toPath.
4. If you only w ant to add the Harmony executables to the %PATH% variable for your ow n user, selectSingle User. If you w ant the Harmony executables to be in the %PATH% variable regardless of w ho
is logged in, select All Users.
5. Select Next.
6. Click on Finish.
7. To verify that the change has been applied, open a new Command Prompt w indow and type thefollow ing command:> echo %PATH%
The path to the Harmony bin folder should be included in the output, separated by other paths
w ith a semi-colon.

18Harmony 22 Installation Guide

About macOS Installation
On macOS, Harmony is provided in an Apple Disk Image (.dmg) file, w hich contains the softw are package. The
installation procedure mostly consists of copying its content to the Applications directory of your macOS
computer.
Installing Harmony on macOS20

Launching Harmony and Side Applications on macOS

21

Adding Harmony Binaries to the $PATH Environment Variable on macOS

22

19

Chapter 1: Basic Installation

Installing Harmony on macOSTo install Harmony on macOS, you must open the Apple Disk Image (.dmg) file, then copy its content to theApplications folder on your machine. You w ill need administrator privileges to be able to add applications to
the Applications folder.

How to install Harmony on macOS
1. In a file brow ser, double-click on the application package you have dow nloaded.
Then the License Agreement prompt appears.
2. If you accept the license agreement presented by the application package, click on the Agreebutton. Otherw ise, click on Disagree.

TIP
If you w ant to see the license agreement in another language, select a language in thelanguage drop-dow n above the license agreement.

3. W ait for macOS to verify the content of the package.
4. In the Finder w indow that opens, selectToon Boom Harmony 22 [Edition].

5. Drag and drop the selected folder over Applications.

NOTE
If you are not logged-in as an administrator user, you w ill be prompted by macOS toenter the log-in and passw ord of a user w ith administrator privileges to authorize
making changes to the Applications folder.

6. W ait for the package to finish copying.
Once the package is done copying, Harmony is installed.

20

Harmony 22 Installation Guide

Launching Harmony and Side Applications on macOS
Harmony is packaged w ith several side applications. How ever, in order to comply w ith the security
requirements of macOS, Harmony is packaged like a single application since Harmony 17. In order to be able
to launch its side applications, you must first launch Harmony, then select a side application from the topmenu.

How to launch a Harmony side application when using Harmony Stand Alone
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition].

2. Double-click on Harmony [Edition].
The main Harmony application launches and the W elcome dialog appears.
3. To launch License W izard, Play, Configuration Assistant or Configuration Editor, open the
Harmony [Edition] top menu, select Tools and, in the sub-menu, select the application you w ant tolaunch.

How to launch a Harmony side application when using Harmony Server
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition].

2. Double-click on Harmony [Edition].
The main Harmony application launches and the log-in dialog appears.
3. Do one of the follow ing:l

If you w ant to launch Control Center, simply click on theControl Center button in thebottom-left corner of the log-in dialog.
l

If you w ant to launch any other side application, such as Paint, Play, Scan, Configuration
Assistant, Configuration Editor, License W izard or Service Launcher, open the Harmony[Edition] top menu, select Tools and, in the sub-menu, select the application you w ant tolaunch.

21

Chapter 1: Basic Installation

Adding Harmony Binaries to the $PATH Environment Variable onmacOS
You can add the path to the Harmony binary files to the $PATH environment variable. This w ill allow you to
run Harmony and its applications and utilities from a terminal by typing the name of the executable files,
w ithout having to type their full path.

How to add Harmony binaries to the $PATH environment variable on macOS
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
3. In the W elcome screen, check the Register console applications in the path option and uncheckall other options.
4. Click on Continue.
5. If you only w ant to add the Harmony binaries to the $PATH variable for your ow n user, selectRegister Path for my user only. If you w ant the Harmony binaries to be in the $PATH variable
regardless of w ho is logged in, select Register Path for all users.

NOTE
You need an account w ith administrator privileges to register the path for all users.

6. Click on Create.
If you selected Register Path for all users, you w ill be prompted to enter an administrator'susername and passw ord to authorize the change.
7. To verify that the change has been applied, open a new Terminal w indow and type the follow ing
command:$ echo $PATH
The path to the Harmony bin folder should be included in the output, separated by other paths
w ith a colon.

22Harmony 22 Installation Guide

About GNU/Linux Installation
On GNU/Linux, Harmony is distributed as an application package in a compressed archive and is bundled w ith
an installation script. Just like a regular installer, the installation script can install the package and add
shortcuts to the applications to your desktop environment, but it is also able to perform the basic configuration
routines if you w ant to install a database or W ebCC server or to set-up a batch processing node.
Harmony is built to support the follow ing operating systems:l

CentOS 6 / Red Hat Entreprise Linux 6lCentOS 7 / Red Hat Entreprise Linux 7 (up to 7.3).

The installation instructions w ill presume you are w orking on a fresh installation of one of these operating
systems.
If you attempt to install Harmony on another GNU/Linux-based operating system, keep in mind that:lThis is not a supported scenario.

lHarmony may crash w hen proceeding to the W elcome screen or main application w indow . This issue isknow n to occur on later versions of CentOS 7 (starting w ith 7.4) as w ell as of Fedora 23 and later. It
may be possible to w ork around this issue—see Troubleshooting a Crash W hen Loading Harmony on
GNU/Linux on page 42.

lHarmony may fail to launch and it may be impossible to w ork around the issue.

lHarmony's daemons may not be compatible w ith the daemon system on your operating system, w hichmeans the use of Service Launcher or the creation of custom-made launch scripts may be required to
set up a database server, a W ebCC server or a batch processing node.

23

Chapter 1: Basic Installation

About GNU/Linux Installation
W hen you install GNU/Linux, you have several options as to the softw are packages that come pre-installed
w ith it. To avoid dependency issues, you should install GNU/Linux w ith a desktop environment and a full suiteof desktop softw are. More specifically:l

W hen installing CentOS 6 or Red Hat Entreprise Linux 6, you should install the Desktop or Software
Development W orkstation softw are set.

l

W hen installing CentOS 7 or Red Hat Entreprise Linux 7, you should install the GNOME Desktop or
Development and Creative W orkstation base environment.

IMPORTANT
It is highly recommended to install the desktop softw are suite for your GNU/Linux distribution
even if you are installing GNU/Linux for a Harmony database server or a license server, as none of
the applications bundled w ith Harmony have been tested to w ork in a minimal environment on
GNU/Linux.

24Harmony 22 Installation Guide

Installing Harmony Dependencies on GNU/LinuxOn GNU/Linux, Harmony requires the follow ing packages to be installed:
l

SDL

l

libX11llibXextllibXrandrlalsa-libllibvorbis

l

libSM

l

fontconfigllibGLUllibjpegllibpng

l

libXi

l

tcsh

l

redhat-lsb

If you have a GNOME Desktop-type installation, most of these w ill be already installed, but at least some ofthese w ill usually need to be installed manually. If you have a minimal installation, all of these packages w illneed to be installed manually.

How to install the Harmony dependencies on GNU/Linux
1. Open a terminal and type in the follow ing command.
$ sudo yum install SDL libX11 libXext libXrandr alsa-lib libvorbis
libSM fontconfig libGLU libjpeg libpng libXi tcsh redhat-lsb
2. W hen prompted, confirm that you w ant to proceed w ith the installation.

25

Chapter 1: Basic Installation

Installing Proprietary Video Drivers on GNU/Linux
Harmony requires that the official (proprietary) drivers for your video card are installed in order to properly use
OpenGL to preview your artw ork and animation. How ever, CentOS and Red Hat Entreprise Linux come w ith afree and open source adaptation of the driver for your graphic card, w ith w hich Harmony is likely to encounter
issues.
Some video drivers come as application packages that are already made to install on your system w ithout ahassle. In this case, all you need to do is obtain the driver from your video card chipset manufacturer andfollow the installation instructions. Some other video drivers are distributed as scripts that build the drivers
into kernel modules. These are more complicated to install and this topic w ill break dow n the process, w hichconsists of the five follow ing steps:
1. Obtain the official video driver from your video card chipset manufacturer's w ebsite.
2. Install the utilities required to build the video driver as a kernel module.
3. Disable the default video driver bundled w ith your operating system.
4. Launch GNU/Linux in terminal mode.
5. Run the official video driver's installation script.

How to know the model of your video card
1. Open a terminal and type in the follow ing command:$ lspci | grep 'VGA compatible controller'
The utility w ill output a line in this format:
01:00.0 VGA compatible controller: <video card model>
W ith this information, you can search for the w ebsite of the chipset manufacturer on the Internet,
and obtain the proper drivers from it.

How to install the utilities required to build the video driver as a kernel module
1. Open a terminal and type in the follow ing command:$ sudo yum install "kernel-devel-uname-r == $(uname -r)" || sudo yum
install kernel-devel
This command w ill install the headers for your Linux kernel, w hich are required to build a kernel
module such as a video card driver. It tries the command for installing kernel headers for an oldkernel and, if that fails, the command for installing kernel headers for the latest version of thekernel, to cover both cases.
2. Enter the follow ing command to install the remaining dependencies:

26

Harmony 22 Installation Guide$ sudo yum install kernel-headers gcc make dkms acpid

How to disable the default drivers on GNU/Linux
1. First, w e must obtain the name of the kernel module used by your video card. To do that, start bygetting the address used by your video card w ith this command:$ lspci | grep 'VGA compatible controller'
The output w ill be in this format:
01:00.0 VGA compatible controller: <video card model>
The numbers before VGA compatible controller are the address of the video card. They
should be in the ##:##.# format. Make note of them.
2. Search the for module associated w ith this address by entering the follow ing command. Replace##:##.# w ith the address used by your video card.
$ find /sys/bus/pci/drivers -name "????:##:##.#"The output w ill look like this:/sys/bus/pci/drivers/nouveau/0000:01:00.0
The name of the folder just under drivers is the name of the kernel module. In this example, it isnouveau, w hich is typically used for NVIDIA graphic cards.
3. Open the list of blacklisted kernel modules in a text editor:$ sudo vi /etc/modprobe.d/blacklist.conf
4. Add the name of the kernel module for your video card to the list of blacklisted modules:
blacklist <name of kernel module>

For example, if the kernel module for your video card is nouveau, you w ould add the follow ing line:
blacklist nouveau

5. Rebuild initramfs. W ith the default video driver added to the blacklist, initramfs w ill be
configured to exclude these drivers from the list of modules it loads on boot, and load the basic
video driver instead:$ sudo mv /boot/initramfs-$(uname -r).img{,~}$ sudo dracut -v /boot/initramfs-$(uname -r).img $(uname -r)
6. Reboot the machine.

27

Chapter 1: Basic Installation

NOTE
After rebooting, it is possible that your display resolution w ill no longer be optimal.
This is a sign that you successfully disabled the default video driver. Your display
resolution w ill be optimal again after you install the proprietary video driver.

7. After logging in, you can verify that the default video drivers are no longer loaded by running thefollow ing command.
$ lsmod | grep "<name of kernel module>"
For example, if the kernel module for your video card w as nouveau, you could use the follow ing
command:$ lsmod | grep "nouveau"
If it returns nothing, GNU/Linux is now running on basic video drivers that w ill not interfere w ith the
installation of proprietary drivers.

How to launch GNU/Linux in terminal mode and run the driver installation utility
1. Reboot your machine.
2. At the GNU GRUB boot menu, use the Up and Dow n arrow to move the cursor to the boot menu
entry that you usually use to boot GNU/Linux.
3. Press the E key.
GRUB opens the selected entry in a text editor, allow ing you to temporarily modify its parameters
for this boot cycle only.

NOTE
The changes you make to the boot menu entry w ill only affect this launch and w ill not
be preserved next time you boot the machine.

4. Using the Up and Dow n key, move the cursor to the line that starts w ith kernel or linux16.
5. Use the End key to move the cursor to the end of that line.
6. Add a space at the end of the line, follow ed by 3. This is a boot parameter that w ill instruct
GNU/Linux to boot at run level 3, w hich means it w ill load a simple terminal w ith netw orking
capabilities.
7. Press Ctrl + X.

28

Harmony 22 Installation Guide

GNU/Linux w ill begin booting. At the end of the process, you w ill be presented w ith a simple
terminal and prompted to log in by typing your username and passw ord.
8. Log in w ith the username and passw ord of a user w ith administrative privileges.
9. Navigate to the directory in w hich you dow nloaded the driver installation utility.
$ cd ~/Downloads
10. Add execute permissions to the utility.
$ chmod +x ./path_to_driver_installer.run
11. Run the utility.
$ sudo ./path_to_driver_installer.run
12. Follow the instruction to install the driver. If the installation is successful, the driver w ill be loaded
next time you boot GNU/Linux.

29Chapter 1: Basic Installation

Installing Harmony on GNU/LinuxTo install Harmony on GNU/Linux, you must extract the package from the .tar.gz archive you dow nloaded,then run the installation script it contains.
You can choose to run the installation script interactively or w ith command line parameters to automate mostof the process.

NOTES
l

If you w ant to run the installation script interactively, your operating system must have thewhiptail command line tool, w hich is provided w ith the newt application package.

l

Even if you install Harmony non-interactively, you must still interactively review and agree tothe license agreement on each installation.

How to install Harmony on GNU/Linux interactively
1. Verify that whiptail is present on your system, to allow the installer to use interactive mode:$ sudo yum install newt
2. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
3. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
4. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package
5. Run the install script.
$ sudo ./install
The interactive setup launches in the terminal.
6. Do one of the follow ing:l

If you are w orking in a Harmony Server environment, w hether your machine is going to be aclient w orkstation or a server, select SERVER and press Enter.

l

If you are w orking in a fully standalone environment or if you only intend to connect to a
Harmony database using W ebCC, select STANDALONE and press Enter.

7. In the components dialog, for each component you w ant to install, use the Up and Dow n keys tohighlight the component, and the Spacebar key to check or uncheck the component:

30Harmony 22 Installation Guidel

APPLICATION: Installs the application files: binaries, libraries, resources, configuration files,
etc. This is required to be able to launch Harmony. You should only omit this option if you areusing the installer to add components to an existing installation. .

l

DESKTOP: Creates a directory in the Applications menu of your desktop environment andadds a shortcut for each Harmony application inside it. This option also allow s you to open ascene in Harmony by double-clicking on an .xstage file in a file brow ser.

l

PATH: Adds the path to the Harmony binaries to your $PATH environment variable,
allow ing you to launch Harmony applications from a terminal by typing their name insteadof their full path.

l

URL: Registers the harmony:// URL scheme so that such URLs launch Harmony. This allow s
W ebCC clients to launch Harmony directly from the w eb brow ser.

If you selected to install Harmony Server, these options w ill also be available:l

PROCESS: Enables the batch processing daemon and adds the current machine to the
database's list of machines available for batch processing.

NOTE
Further configuration is required to make this machine a w orking batchprocessing node.

l

DATABASE: Enables the database server daemon and, if no database is present on themachine, creates an empty database file system on the local machine.

l

LINK: Enables and configures the link server daemon. This is required if the current machineis meant to be a database server for W indow s clients.

l

W EBCC: Enables and configures the W ebCC daemon. This w ill make this machine a
W ebCC server.

l

OPENH264: Dow nloads and installs the Cisco OpenH264 library. This allow s a W ebCC
server to create preview videos for the database scenes w hich can be played in a w eb
brow ser. An Internet connection is required.

l

UPDATEDB: Replaces the dictionary (.dict) files in this machine's database w ith thispackage's dictionary files. This is useful if your machine is a database server, and you are
currently upgrading its version of Harmony.

8. Press the Tab key to sw itch to the Ok button at the bottom, then press Enter.
9. In the Installation Directory dialog, you can choose to type a custom installation path, or to use thedefault one. Then, press Enter.

31

Chapter 1: Basic Installation

10. In the License Agreement dialog, take the time to carefully review the license agreement. Use theUp and Down keys to scroll through the text in the agreement and read it until the end.
11. Press Tab to sw itch to the AGREE and DISAGREE buttons. You can use the Left and Right keys to
sw itch betw een selecting the AGREE or the DISAGREE button:l

If you agree w ith the license agreement, select the AGREE button and press Enter.

l

If you disagree w ith the license agreement, select the DISAGREE button and press Enter.

12. A dialog w ill prompt you to confirm each component that you elected to install. If a lot ofcomponents are listed, you can use the Up and Down keys to scroll through the list. You can use
the Left and Right keys to select Yes or No. If you w ant to proceed, select Yes and press Enter.
13. The installation begins. Each step of the installation is explained in detail until the installation isover.
14. If your product is not activated, do one of the follow ing to launch the License W izard:l

In the terminal, type the follow ing command:$ sudo /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/LicenseWizardl

In the GNOME top menu, select Applications > Harmony 22 [Edition] > License W izard.
A terminal w ill open, prompting you to enter your user passw ord. This terminal is
attempting to launch License W izard w ith sudo, as it requires elevated privileges. Type inyour passw ord and press Enter.

For information on how to use the License W izard to activate Harmony, see the Toon Boom License
Activation Documentation at the follow ing address:
https://docs.toonboom.com/help/activation
15. Once Harmony is installed and activated, you can start using it. How ever, if you elected to add thepath to Harmony's binaries to your $PATH environment variable, you w ill need to reboot yourmachine before you can benefit from this feature.

How to install Harmony on GNU/Linux non- interactively
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz

32Harmony 22 Installation Guide

3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package
4. Start typing the command to run the installer w ith all the parameters you w ant for yourinstallation:$ sudo ./install <parameters>

NOTE
Each parameter must be specified separately. For example: -a -p w ill w ork, but not ap.

Parameter

Description

Installation modes

Installs the application w ith shortcuts to the server applications and w ith
daemon files for database servers and clients.
-server

NOTE
If no installation mode is specified, this one is implied by default.

-standalone

Installs the application w ithout the shortcuts to the server applications
and w ithout the daemon files for database servers and clients. Only use
this option if you intend to use Harmony on this machine w ithout relying
on a Harmony Server database.

-uninstall

Uninstalls the specified components instead of installing them. If
specified alone, this launches the uninstaller in interactive mode.

Optional components-a-application

Installs the application files: binaries, libraries, resources, configuration
files, etc. This is required to be able to launch Harmony. You should only
omit this option if you are using the installer to add components to an
existing installation. .

33

Chapter 1: Basic Installation

Parameter

Description-b

For backw ard compatibility w ith older versions of the installer, thisinstalls the application files and adds the path to the Harmony binaries
to the $PATH environment variable. It is equivalent to -a -e.

-binaries-de-desktop

Creates a directory in the Applications menu of your desktop
environment and adds a shortcut for each Harmony application inside it.
This option also allow s you to open a scene in Harmony by double--kde

clicking on an .xstage file in a file brow ser.

-d

Enables the database server daemon and, if no database is present on
the machine, creates an empty database file system on the local
machine.

-dbserver-l-linkserver

Enables and configures the link server daemon. This is required if thecurrent machine is meant to be a database server for W indow s clients.

Enables the batch processing daemon and adds the current machine tothe database's list of machines available for batch processing.
-p-process

NOTE
Further configuration is required to make this machine a w orking
batch processing node.

-w-w ebccserver-oh-openh264

Enables and configures the W ebCC daemon. This w ill make this machinea W ebCC server.

Dow nloads and installs the Cisco OpenH264 library. This allow s a
W ebCC server to create preview videos for the database scenes w hichcan be played in a w eb brow ser. An Internet connection is required.

Configuration sw itches

-e
-env

Adds the path to the Harmony binaries to your $PATH environment
variable, allow ing you to launch Harmony applications from a terminal

34

Harmony 22 Installation Guide

Parameter

Description

by typing their name instead of their full path.

-s-schemeregister-u-updatedict

Registers the harmony:// URL scheme so that such URLs launch
Harmony. This allow s W ebCC clients to launch Harmony directly fromthe w eb brow ser.

Replaces the dictionary (.dict) files in this machine's database w ith thispackage's dictionary files. This is useful if your machine is a databaseserver, and you are currently upgrading its version of Harmony.

Other options-hDisplays information about how to use the install script.
-help-target <PATH>

Specifies the directory in w hich to install the application. If not specified,Harmony w ill be installed in /usr/local/ToonBoomAnimation/harmony[Edition]_22-dbpath <PATH>

Specifies the location of the database on this machine's file system. This
option is only relevant if installing a database server w ith the -d option,
installing a W ebCC server w ith the -w option or updating dictionary(.dict) files w ith the -u option. If not specified, the installer w ill presume
that the database is located in /USA_DB.

-ow n-ow n <USER>-ow n <USER:GROUP>

Makes the application files ow ned by the specified user or by the
specified user:group. If no user or user:group is specified, this w ill makethe application files ow ned by the user running the script. If this option is
not specified, application files w ill be ow ned by the root user.

-q
Do not output information during the installation process.
-quiet-v-verbose

Output detailed information on each step of the installation process,including every file copied.

35

Chapter 1: Basic Installation

Parameter

Description-output <PATH>

W rites the installation log to the specified file instead of outputting it to
the terminal.

Disables the use of the whiptail utility to display dialogs andinteractive prompts. This mode is compatible w ith dumb-type terminals,
w hich do not support scrolling or erasing the screen.
-nodialog

NOTE
This option is automatically enabled if the whiptail utility is notfound on the machine or if the installer detects that the terminal isunable to scroll or erase the screen.

By default, installing over an existing installation w ill simply overw rites
existing files, except for configuration files in the etc directory of theinstalled application, w hich the installer preserves. This option w ill cause
the existing installation to be completely deleted before installing.
-forceIMPORTANT
Enabling this option w ill cause your Harmony configuration files tobe erased permanently.

-yAssumes yes on all prompts, except for the license agreement.
-assumeyes

5. Press Enter.
The install script launches and, if the parameters are valid, the License Agreement prompt appears.
6. In the License Agreement dialog, take the time to carefully review the license agreement. Use theUp and Down keys to scroll through the text in the agreement and read it until the end.
7. Press Tab to sw itch to the AGREE and DISAGREE buttons. You can use the Left and Right keys to
sw itch betw een selecting the AGREE or the DISAGREE button:l

If you agree w ith the license agreement, select the AGREE button and press Enter.

l

If you disagree w ith the license agreement, select the DISAGREE button and press Enter.

36

Harmony 22 Installation Guide

8. A dialog w ill prompt you to confirm each component that you elected to install. If a lot ofcomponents are listed, you can use the Up and Down keys to scroll through the list. You can use
the Left and Right keys to select Yes or No. If you w ant to proceed, select Yes and press Enter.
9. The installation begins. Each step of the installation is explained in detail until the installation isover.
10. If your product is not activated, do one of the follow ing to launch the License W izard:l

In the terminal, type the follow ing command:$ sudo /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/LicenseWizardl

In the GNOME top menu, select Applications > Harmony 22 [Edition] > License W izard.
A terminal w ill open, prompting you to enter your user passw ord. This terminal is
attempting to launch License W izard w ith sudo, as it requires elevated privileges. Type inyour passw ord and press Enter.

For information on how to use the License W izard to activate Harmony, see the Toon Boom License
Activation Documentation at the follow ing address:
https://docs.toonboom.com/help/activation
11. Once Harmony is installed and activated, you can start using it. How ever, if you elected to add thepath to Harmony's binaries to your $PATH environment variable, you w ill need to reboot yourmachine before you can benefit from this feature.

37

Chapter 1: Basic Installation

Adding Harmony Binaries to the $PATH Environment Variable on
GNU/Linux
You can add the path to the Harmony binary files to the $PATH environment variable. This w ill allow you to
run Harmony and its applications and utilities from a terminal by typing the name of the executable files,
w ithout having to type their full path.

How to add Harmony binaries to the $PATH environment variable on GNU/Linux
1. In a Terminal, navigate to the location w here you previously extracted the Harmony package for
installation—see Installing Harmony on GNU/Linux.
$ cd ~/Downloads/name-of-package
2. Run the installation script w ith the -e option.
$ sudo ./install -e
The Toon Boom Harmony license agreement prompt appears.
3. In the License Agreement dialog, take the time to carefully review the license agreement. Use theUp and Down keys to scroll through the text in the agreement and read it until the end.
4. Press Tab to sw itch to the AGREE and DISAGREE buttons. You can use the Left and Right keys to
sw itch betw een selecting the AGREE or the DISAGREE button:l

If you agree w ith the license agreement, select the AGREE button and press Enter.

l

If you disagree w ith the license agreement, select the DISAGREE button and press Enter.

5. A dialog w ill prompt you to confirm that you w ant to add the path to the Harmony binaries to the$PATH environment variable. You can use the Left and Right arrow keys to select Yes or No. SelectYes and press Enter.
The install script w ill add the path to the Harmony binaries to the $PATH environment variable.
6. To verify that the change has been applied, open a new Terminal w indow and type the follow ing
command:$ echo $PATH
The path to the Harmony bin folder should be included in the output, separated by other paths
w ith a colon.

38Harmony 22 Installation Guide

About Audio Transcoding on GNU/LinuxOn GNU/Linux, by default, Harmony can only play audio files w ith these specifications:lFormat: W aveform Audio File (.w av)lSample rate: 22 050 HzlSample size: 16 bitsl

Channel mode: Stereo

If FFmpeg is installed on your system, Harmony w ill use it to transcode other audio formats into this format on
the fly. How ever, FFmpeg comes bundled w ith patented algorithms such as encoders and decoders, theunlicensed use of w hich may contravene intellectual property law s in your jurisdiction. Hence, if you use
Harmony on GNU/Linux, it is recommended to transcode your audio in the format specified above using thirdparty softw are before importing it to your Harmony scene.

39

Chapter 1: Basic Installation

Preventing the Alt Key Keyboard Shortcut Conflict Between Harmony
and the GNU/Linux Desktop
By default, in GNOME 2 and KDE, clicking anyw here on a w indow w hile holding the Alt key dow n w ill movethe w indow . Because the Alt key is used as a modifier for some draw ing and animations tools in Harmony, thismay come in conflict w ith Harmony functionalities. Hence, it is highly recommended to configure your desktop
environment to use the Super (W indow s) key for moving w indow s instead.

How to change the window moving keyboard shortcut in GNOME 2
1. In the GNOME top menu, select System > Preferences > W indows.
The W indow Preferences dialog appears.
2. In the Movement Key section, select Super (or "W indows Logo")
3. Click on Close.

How to change the window moving keyboard shortcut in KDE
1. In the KDE menu, select Computer > System Settings.
2. In the System Settings w indow , select the W indows Behavior icon.
3. Select the W indow Actions tab.
4. In the Modifier Key drop-dow n, select Meta.
5. Click on Apply.

40

Harmony 22 Installation Guide

Troubleshooting Problems with Harmony on GNU/LinuxThe follow ing section explains how to fix common issues w ith Harmony on GNU/Linux.

41

Chapter 1: Basic Installation

Troubleshooting a Crash W hen Loading Harmony on GNU/Linux
If Harmony crashes w hen opening a scene or proceeding to the offline w elcome screen, returning the message"segmentation fault" to the terminal, this may be caused because Harmony is not compatible w ith later
versions of OpenSSL. You can fix this by setting the OPENSSL_ia32cap environment variable to the value"~0x200000200000000". This can be done in three different w ays:lSetting the environment variable in a terminal and launching Harmony from this terminal.

TIP
You should attempt this first to make sure that setting this environment variable actually
solves the problem.

lSetting the environment variable for one user, and launching Harmony w hen logged in as this user.

l

Setting the environment variable for the entire machine, allow ing you to launch Harmony as any user.
This requires an account w ith administrator privileges.

How to set the OPENSSL_ia32cap environment variable in a terminal and launch
Harmony
1. Open a terminal and enter the follow ing command:$ export OPENSSL_ia32cap="~0x200000200000000"
2. Launch Harmony from the same terminal:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/Harmony[Edition]

How to set the OPENSSL_ia32cap environment variable for the current user
1. Open a terminal and open your Bash shell login file:$ vi ~/.profile
2. Add the follow ing line at the end:
export OPENSSL_ia32cap="~0x200000200000000"
3. Save and quit.
4. Open your C-shell login file:$ vi ~/.login
5. Add the follow ing line at the end:42Harmony 22 Installation Guide

setenv OPENSSL_ia32cap "~0x200000200000000"
6. Save and quit.
7. Log out, then log back in.
8. Attempt to launch Harmony.

How to set the OPENSSL_ia32cap environment variable for all users
1. Create a new Bash boot script using the follow ing command:$ sudo vi /etc/profile.d/openssl.sh
2. In the script, type the follow ing command:
export OPENSSL_ia32cap="~0x200000200000000"
3. Save and quit.
4. Create a new C-shell boot script using the follow ing command:$ sudo vi /etc/profile.d/openssl.csh
5. In the script, type in the follow ing command:setenv OPENSSL_ia32cap "~0x200000200000000"
6. Save and quit.
7. Reboot the machine.
8. Attempt to launch Harmony.

43

Chapter 1: Basic Installation

Troubleshooting Desktop Shortcuts Launching the W rong Version ofHarmony
If you have several older versions of Harmony installed, it is possible that some of their shortcuts launch thew rong of Harmony. This is because, prior to Harmony 15.0, desktop shortcuts created for Harmony w ould not
point to the full path of applications, so they launched the version of the application in the $PATH environment
variable.
A script has been made to fix this issue. It w ill go through every installation of Harmony in the default
installation location and create shortcuts for them w ith the proper configuration.
You can dow nload the script from the follow ing location:
https://docs.toonboom.com/dow nload/tools/fix_harmony_shortcuts.sh

NOTE
This script w ill only w ork for installations of Harmony that are located in the default directory:/usr/local/ToonBoomAnimation.

How to launch the desktop shortcut fixing script
1. In a terminal, go to the directory w here you dow nloaded the script.
$ cd <download directory>
2. Add execution privileges to the script.
$ chmod +x fix_harmony_shortcuts
3. Run the script w ith elevated privileges:$ sudo ./fix_harmony_shortcuts
4. Read the confirmation prompt, then type yes and press enter.

44Harmony 22 Installation Guide

45

Chapter 2: Harmony Server

Chapter 2: Harmony Server
Harmony Server is a team-based infrastructure for animation production. Its array of cutting-edge features
increases productivity and encourages creativity. Developed in conjunction w ith leading studios w orldw ide,
Harmony is specifically designed for long-term episodic and feature length projects, providing a true
animation pipeline. Several animators can w ork simultaneously on the same scene w hile the asset libraryprovides users w ith easy access to up-to-date media assets.

Harmony Server is truly scalable; more than 100 staging clients can share animation just as easily as a few
can. W hether you are a start-up studio or a large established animation facility, Harmony serves as theanimation backbone ensuring sustainability and grow th.
Harmony Server is a pow erful solution that brings together multiple teams w orking on the same project,w hether in-house or remotely. The Harmony Serversolution offers a robust asset management system thatenables users to quickly locate assets, share tasks on complex scenes and centralize all assets in a common
repository. Tremendous gains in efficiency and quality are made by the teams, w ho enjoy a smooth flow
betw een each task, and more time dedicated to their creative assignments.
In addition, the server is critical at the end of a production for rendering projects efficiently. The rendering
process, controlled directly by the server, not only renders production scenes but also executes the batch
vectorization of the scanned draw ings. You can send an unlimited number of scenes to render and change theirpriorities depending on your deadline. You can also render final frames locally or batch process over a netw ork
in the background or at scheduled times. For more information, see Batch Processing on page 294.

46

Harmony 22 Installation Guide

About the Harmony Server Structure
The primary purpose of the database server is to host and manage the information on its Harmony scenes.
Optionally, it can also host the actual scene data, but other machines on your netw ork can be used for scene
data storage as w ell, as those are tw o different components of a Harmony database.
A Harmony database is structured using different netw ork shares:l

The /USA_DB share, w hich contains the information on all the scenes, environments, jobs as w ell asshared assets such as palettes and templates stored in environments or jobs. This part of the databasemust be hosted on the machine that runs the database server service/daemon, to w hich client
w orkstations w ill connect directly.

l/usadata shares, w hich contain the actual scene data: the draw ings, animation, 3D models, scene
palettes, etc. Those can be hosted on the database server or on any machine on the local netw ork thatthe client w orkstations can access. There can be as many as the studio needs, w hich allow s you to
expand the storage capacity of your database server by creating a new /usadata share on a new fileserver.

On client machines, every netw ork share is mounted on the same location as the location of the actual shareon their respective server. Likew ise, if other servers are used to store scene data, the shares of these servers
are mounted on the database server. The result is that the database file structure is entirely accessible on allmachines in the netw ork.
If you intend to use several /usadata shares, they must be numbered them. The best practice is to name thefirst /usadata share /usadata000, and it is typical, although not mandatory, to store that share on the samemachine as the database server. Then, w hen you need to expand the storage space for your Harmony
database, you can create a share named /usadata001 on another machine, and another one named/usadata002 on another machine, etc.
In the end, client machines w ill locate the different shares that compose your database by mounting thoseshare points on the client machine's filesystem root.
On W indow s machines, this is done by adding shortcut (.lnk) files in the root of a drive (typically C:) w hichpoint to the netw ork path of the share, for example:l

A USA_DB.lnk shortcut file pointing to \\dbserver\USA_DB.

l

A usadata000.lnk shortcut file pointing to \\dbserver\usadata000.

l

A usadata001.lnk shortcut file pointing to \\newfileserver\usadata001.

This process is automatically done by Configuration W izard, a W indow s-exclusive configuration tool for
Harmony.
On macOS and GNU/Linux machines, this is done by mounting the shares on folders located at the root of thefilesystem. By giving those folders the name of their respective shares, it simulates the presence of theserver's files on the machine's filesystem. For example:

47

Chapter 2: Harmony ServerlA directory named /USA_DB is mounted w ith the NFS share at address dbserver:/USA_DB.

l

A directory named /usadata000 is mounted w ith the NFS share at address
dbserver:/usadata000.

l

A directory named /usadata001 is mounted w ith the NFS share at address
newfileserver:/usadata001.

Typically, clients and servers can communicate w ithout any issue if they use the same kind of operating
system. It is possible to set-up a Harmony database that mixes different platforms across the database server,
the file servers and the client w orkstations, but w ith some important limitations that must be taken in account:l

By default, the use of non-alphanumerical Unicode characters, w ith the exception of the dash and theunderscore, in Harmony for naming scenes, layers and draw ings is not enabled, but can optionally beenabled. How ever, you must absolutely keep in mind that macOS and GNU/Linux typically fail tocommunicate filenames containing Unicode characters over the NFS protocol. This means that if
Unicode is enabled on your database, and that a macOS based client tries to open or save a scene
containing Unicode characters which is hosted on a GNU/Linux- based file server, Harmony will failto open and save files with Unicode characters in their name, and there might be data loss! Hence, it
is important to never enable Unicode if your netw ork includesmacOS-based clients and GNU/Linuxbased database servers or file servers, including GNU/Linux-based NAS servers.

l

If you set up your database server on a W indow s machine, only W indow s clients are supported. It may
be possible to connect a macOS-based or GNU/Linux-based client w orkstation to a W indow s-based
database server, but this may cause unexpected issues and it is not a supported usage scenario.

l

If you intend to set up your database server on a macOS machine and you w ant W indow s w orkstations
to be able to connect to it, you w ill need to install a third party softw are, SMBup, and configure it toshare your database files through the Samba protocol. This is because macOS natively supports the
NFS sharing protocol, but not SMB, and W indow s natively supports the SMB file sharing protocol, but
not NFS.

To summarize, here is a table outlining the implications of mixing platforms betw een servers and clients:↓ Client

W indows

macOS

GNU/Linux

W indows

No problem.

Requires SMBup to beinstalled and configuredon the server.

No problem.

macOS

Not supported.

No problem.

Unicode must be
disabled.

GNU/Linux

Not supported.

Unicode must be
disabled.

No problem.

Server →48

Harmony 22 Installation Guide

About Database Server Installation
At the heart of the Harmony Server solution is the server itself, w hich centralizes all the production assets in a
repository. Loaded w ith production proven tools to manage administration tasks, the server is completely
flexible and w ill fit in w ith your existing infrastructure, w hether you're on W indow s, Mac or Linux.
The first step to having a Harmony Server netw ork is to set up the database server. The database server
contains the structure of the database and runs a programs that allow s client w orkstations to open and edit
scenes remotely.
Installing a database server can be done on all platforms supported by Harmony: W indow s, macOS and
GNU/Linux. Although the installation procedure is substantially different on each platform, they all have thesame basic components:lCreating a database file structure and a scene data storage space.

lSharing the database files using the Samba (W indow s) or NFS (macOS or GNU/Linux) file-sharing
protocol, so that other machines can access them.

lConfiguring the database server program, w hich handles client requests, to run on startup or login.

Because of the differences in the w ay W indow s and UNIX filesystems w ork, and in the w ay W indow s, macOSand GNU/Linux support filesharing, extra steps are required if you need to allow W indow s clients to connect
to a macOS or GNU/Linux-based server, mainly:lSharing the database files using the Samba file-sharing protocol.

lConfiguring the link server program, w hich handles the creation of symbolic links for W indow s clients.

Additionally, it may be required to add security exceptions to the server machine's firew all for the databaseserver, the link server and the file sharing services used by the server.
Optionally, a server machine's firew all can be fully disabled to allow open communications betw een different
machines on the site. How ever, a dedicated firew all should be set-up at the site level to ensure computers
outside of the site cannot attack machines on the site.

IMPORTANT
Although it may be possible to use macOS or GNU/Linux based client w orkstations to connect to a
W indow s based database server, this is not a supported usage scenario and attempting this may
cause unexpected problems.

49

Chapter 2: Harmony Server

Database Server Installation on W indows
On W indow s, the basic setup for a database server is done through the Configuration W izard, w hich w illcreate the base structure of the database and automatically configure the database server service.
Disabling the Firewall for a Harmony Database Server on W indows

51

Setting up the Database Server on W indows

52

Removing the Scene Data Storage from the Database Server on W indows

54

Running the Database Server Service on Log- In on W indows

55

Opening the Firewall Ports for a Harmony Database Server on W indows

57

Creating a Scene Data Storage Space on W indows

59

Configuring a W indows Database Server to have a Static IP Address

65

Looking Up the Database Server Log on W indows

69

Launching the Database Server Manually on W indows

70

How to Stop and Restart the Database Server on W indows

71

Pausing and Resuming the Database Server on W indows

73

Uninstalling the Database Server on W indows

74

50

Harmony 22 Installation Guide

Disabling the Firewall for a Harmony Database Server on W indows
By default, the W indow s firew all w ill block incoming connections to a database server. This installation guideprovides instructions on how to add exceptions for the database server to your firew all. How ever, you may
prefer to disable the firew all completely so as to simplify the installation process or to rule out the firew all as
a possible cause w hen troubleshooting an issue.

IMPORTANT
If you choose to disable the firew all on W indow s, it is critical to ensure that your domain has
effective site-w ide security measures to prevent unauthorized access to your database server.

How to disable the firewall on W indows
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, select System and Security.
3. Under W indows Defender Firewall, select Check firewall status.
4. In the list to the left, select Turn W indows Defender Firewall on or off.
5. Under Domain network settings, select Turn off W indows Defender Firewall (notrecommended).
6. Under Private network settings, select Turn off W indows Defender Firewall (notrecommended).
7. Under Public network settings, select Turn off W indows Defender Firewall (not recommended).
8. Click on OK.

51

Chapter 2: Harmony Server

Setting up the Database Server on W indows
Using the Toon Boom Harmony Configuration W izard, you can quickly create the basic structure for a
Harmony database and install the database server as a W indow s service, w hich w ill run as user usabatch.

How to set up a Harmony database server on W indows
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
3. In the list of tasks, right of Database, click on the ... button.
4. In the Toon Boom Harmony Database Creation dialog, select Server/Standalone and click on Next.
5. Under W hat drive should be used for the database?, select w hich drive on this machine should be
used to store the database's files.

NOTE
A USA_DB directory w ill be created at the root of the selected drive.

6. Under W hat is the UserName?, type in the username of the user account you w ant to create forthe database server service. This w ill create a local user account on your W indow s machine, andthis user w ill be connecting to the netw ork and running the service. By default, this use is named
usabatch.

TIP
If you already configured a user for a database server or the batch processing service on
this machine before, you can type in the name of that existing user. The Configuration
W izard w ill use this existing user account to run the database server service instead ofcreating a new one.

7. Under W hat is the User Password?, type in the passw ord for the user that w ill run the databaseserver service. If you are creating a new user, use this field to select their passw ord. If you typed in
the user name of an existing user account, type in their actual passw ord.
8. Click on Next.
The Scene Data Location dialog appears. In this dialog, you can create a scene data storage on thismachine. By default, this dialog is already configured to add a single scene data storage to thismachine, on the drive C, named usadata000.

52

Harmony 22 Installation Guide

9. In the User Name and Passw ord fields, make sure the credentials for the scene data location thatw ill be created on your machine match the ones entered for the database server, typed in steps 5
and 6.
10. Click on Next.
11. In the Database changes field, verify that that the changes the w izard is about to make are correct,
then click on Finish.
Your database is set-up. At this point, you should already be able to run Control Center from thismachine, log-in w ith the default user usabatch and create scenes and users.

53

Chapter 2: Harmony Server

Removing the Scene Data Storage from the Database Server on
W indows
By default, Configuration W izard w ill add a scene data storage space to the server w hen creating a databaseserver. If you w ant all of the scene data storage spaces to be on other machines than the database servermachine, you must first remove that storage space from the server, then create a scene data storage space onanother machine.

How to remove the scene data storage space from a W indows database server
1. Open an Explorer w indow .
2. Navigate to the root of the drive in w hich the scene data storage space w as created. By default, thisdrive is C:.
3. Select the directory usadata000.
4. Delete this directory.
5. Open the Start menu and, in the Programs list, select W indows Accessories.
6. Right-click on Notepad and select Run as Administrator.
7. In the top menu of Notepad, select File > Open.
8. In the Open dialog, select All Files (*.*) in the file type drop-dow n in the bottom-right corner.
9. Brow se to and select the follow ing file:
C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\etc\server.ini
In the file, there are numerous lines starting w ith FileSystem. The first one of them w ill most
likely contain information about the scene data storage space the Configuration W izard created.
For example, if the name of the server is harmonyserver, this line w ould contain:
FileSystem0=C usadata000 harmonyserver
10. On this line, remove all of the information after the equal sign for FileSystem0:
FileSystem0=
11. In the top menu, select File > Save.
The storage space has now been removed from your database server. To create another storage
space on a different machine, see Creating a Scene Data Storage Space on W indow s.

54Harmony 22 Installation Guide

Running the Database Server Service on Log- In on W indows
W hen creating a database server w ith Configuration W izard, the database service is configured to launch as
an actual W indow s service. This means it launches and allow s clients to connect as soon as the machine isbooted, w ithout any user being signed-in.
Using Service Launcher, it is possible to configure your database server to only launch its database server
service as the logged-in user, w hen they log-in. This means the database w ill only be accessible if the user
configured to run it is logged in.
Although this may seem impractical, it may be preferable for security reasons. Services installed w ith theConfiguration W izard are run under the user usabatch, an user w ith administrator privileges w hich is createdby Configuration W izard to launch the services. W hen using Service Launcher, the logged-in user does notneed to have administrator privileges to run services.
Before configuring Service Launcher to run the database server, the w indow s service that launches it must be
disabled, so as to avoid launching tw o instances of the database server.

NOTE
W hile W indow s services run regardless of w ho is logged in and even w hen no user is logged-in,
Service Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in.
This means that if you w ant Service Launcher to launch w hen any user is logged in, you must
configure it for each user that has access to the machine.

How to disable the database server service
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- tbdbserver.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on Remove.
From that point on, the database server service w ill no longer launch on boot.
6. Close the Control Panel.

55

Chapter 2: Harmony Server

How to configure the database server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

2. Do one of the follow ing:l

If Service Launcher is not running, open the Start menu and, in the Programs list, selectHarmony 22 [Edition] > Tools >lService Launcher.

If Service Launcher is already running, click on its iconin the notification tray.

The Service Launcher application launches.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the Database Server tab.
5. Click on Launch to verify that the database server launches successfully through Service Launcher.
6. Check the Launch when Service Launcher starts option.
7. In the top menu, select Server > Save All Settings.
From now on, the database server w ill launch through Service Launcher w hen you log in.

56

Harmony 22 Installation Guide

Opening the Firewall Ports for a Harmony Database Server on
W indows
By default, the W indow s firew all w ill block the communication betw een client w orkstations attempting toconnect to the Harmony server and the database server service. In order to allow clients to connect to yourserver, you must open the ports used by the database server on the server machine.

How to open the ports for the Harmony database server on W indows
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. Click on System and Security.
3. Click on W indows Defender Firewall.
4. Click on Advanced settings.
The W indow s Defender Firew all w ith Advanced Security w indow opens.
5. In the list to the left, select Inbound Rules.
6. In the Actions list to the right, select New Rule.
The New Inbound Rule W izard appears.
7. Under W hat type of rule would you like to create?, select Port and click on Next.
8. Under Does this rule apply to TCP or UDP?, select TCP.
9. Under Does this rule apply to all local ports or specific local ports?, select Specify local ports.
10. In the text field, type the port number 5680.

NOTE
This is the default port used by the Harmony database server. How ever, the port
number for the database server can be customized by editing the Dbserver.conf filelocated in /USA_DB.

11. Click on Next.
12. Under W hat action should be taken [...], select Allow the connection and click on Next.

57

Chapter 2: Harmony Server

13. Under W hen does this rule apply?, check the netw ork types over w hich clients w ill attempt toconnect to this server, then click on Next.
14. In the name field, name the rule "Toon Boom Database Server".
15. Click on Finish.
Clients on your netw ork w ill now be able to communicate w ith the database server.

58

Harmony 22 Installation Guide

Creating a Scene Data Storage Space on W indows
You can create additional storage spaces for your Harmony database on different W indow s machines. The
database server w ill connect to these machines to transmit scene data to the clients, allow ing you to expand
the storage capacity of your database.
The first step is to create a shared folder on the W indow s machine that w ill host the new storage space. Then,
you must configure your database server w ith the information about this new storage space so that, w hen
using Configuration W izard to set up new Harmony Server clients, this new share w ill be added to the client
configuration. Lastly, if you w ant the database server itself to have access to the new storage space, you must
add a shortcut to that storage space's netw ork path on the database server.
If you intend to configure your database server and the scene data storage spaces to require credentials to beaccessed, you should configure all the shares to be accessible w ith the same user names and passw ord, asHarmony clients w ill only use one set of credentials to connect to the database and the different scene data
storage spaces. For example, in an open netw ork environment, it is typical to give access to all the Harmonyrelated netw ork shares to the user usabatch.

How to create the user usabatch on a new W indows- based scene data storage server
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, click on System and Security.
3. In the System and Security panel, click on Administrative Tools.
4. Double-click on Computer Management.
5. In the Computer Management dialog, in the navigation tree to the left, select Local Users andGroups > Users.
6. In the Actions panel to the right, select More Actions > New User.
7. In the New User dialog, enter the desired credentials for the user that w ill be used to access the
netw ork share. For example:lUser name: usabatchlFull name: usabatchl

Password: usabatchl

Uncheck the User must change password at next logon option.

59

Chapter 2: Harmony ServerlCheck the User cannot change password option.

l

Check the Password never expires option.

8. Click on OK.

How to create a scene data storage space on W indows
1. Log-in to the machine that w ill be used as the new scene data storage space using an account w ith
administrator privileges.
2. Open an Explorer w indow .
3. Brow se to the root of the drive w here you w ant the scene data to be stored (ie: C:).
4. Create a new directory.
5. Name the directory usadata, follow ed by a padded, zero-based number indicating its index in thelist of storage spaces used by yourHarmony database. For example, if this is the second storage
space your add to your database, name it usadata001.
6. Right-click on the folder and select Properties.
7. Open the Sharing tab.
8. Click on Advanced Sharing.
9. In the Advanced Sharing dialog, check the Share this folder checkbox.
10. Click on Permissions.
11. In the Group or user names list, select Everyone.
12. Check the checkbox right of Full Control, under the Allow column.
13. Click on OK.
14. In the Advanced Sharing dialog, click on OK.
15. In the Properties dialog, click on Close.

How to add the a new scene data storage space to your server configuration
1. Log in to the database server.
2. Open the Start menu and, in the Programs list, select W indows Accessories.
3. Right-click on Notepad and select Run as Administrator.
4. In the top menu of Notepad, select File > Open.

60

Harmony 22 Installation Guide

5. In the Open dialog, select All Files (*.*) in the file type drop-dow n in the bottom-right corner.
6. Brow se to and select the follow ing file:
C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\etc\server.ini
In the file, there are numerous lines starting w ith FileSystem follow ed by a number, an equal
sign, and some of them w ill have information after the equal sign. This is the list of scene data
storage spaces used by your Harmony server. For example, a new ly created database w ith a single
storage space w ill probably have this scene data storage space configuration:[WizardConfig]
ServerName=SERVERNAME
InstallationDrive=C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22 [Edition]
UsaShare=usa
UsadbDrive=C
UsadbShare=usa_db
FileSystem0=C usadata000 SERVERNAMEFileSystem1=
FileSystem2=
FileSystem3=
FileSystem4=
[...]

NOTE
The server.ini file generated by Configuration W izard contains a file system listing
going from 0 to 99. The sample file w as shortened here to avoid cluttering the
documentation.

7. In the first one of the FileSystem lines that has nothing after the equal sign, type in theinformation for your scene data server, in the follow ing format:
FileSystem1=<drive letter> <share name> <server name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<drive letter>: The driver letter of the drive on w hich the scene data storage space islocated, w ithout any colon or backslash. For example, if the scene data storage space w ascreated on drive C:, simply type C.

l<share name>: The name of the share containing the scene data. Usually, this share iseither named USADATA or usadata, and its name may be follow ed by a zero-padded, zero-61

Chapter 2: Harmony Server

based number indicating the index of the scene data storage space. For example, the firstscene data storage space could be named USADATA or usadata000.
l<server name>: The host name of the scene data server. If the scene data storage space ishosted on the same machine as the database, then this host name is the same as the hostname for the database.

For example, if the new scene data storage space is the second scene data storage space for theserver, and is located in C:\usadata001 of a computer w ith the hostname newserver, theappropriate configuration for this w ould be as follow s:
FileSystem1=C usadata000 newserver

8. In the top menu, select File > Save.
From now on, the next time you run the Configuration W izard to set up a Harmony database client
on W indow s, the new scene data storage space w ill be automatically added to the client
configuration. You can use the Configuration W izard to re-configure existing clients, if needed.

How to connect the database server to a new remote scene data storage space
1. Log in to the database server.
2. Open the Start menu and, in the Programs list, select Harmony 22 [Edition] > Tools > Control
Panel.
3. W hen prompted, allow Control Panel to make changes to your device.
4. In the Control Panel, open the Connections tab.
5. In the Sharename field, type in the netw ork (UNC) path of the new scene data storage space. Thislocation should start w ith tw o backslashes follow ed by the hostname of the server on w hich thisstorage space is hosted, follow ed by a backslash, then the name of the scene data storage space
itself, like in the follow ing example:\\newserver\usadata001
6. In the Username field, type in the name of a user w ho has access to this netw ork share.
7. In the Password field, type in this user's passw ord.
8. Click on Create Connection.
9. Click on Close.
10. Right-click on the desktop, then select New > Shortcut.
The Create Shortcut dialog appears.

62Harmony 22 Installation Guide

11. Under Type the location of the item:, type the netw ork (UNC) path of the new scene data storage
space, as in step 5.
12. Click on Next.
13. Under Type a name for this shortcut:, type in the name of the share and nothing else. For example,
if the shortcut path is \\newserver\usadata001, the name of the shortcut should beusadata001.
14. Click on Finish.
15. Right-click on the shortcut and select Cut.
16. Open an Explorer w indow .
17. Brow se to the root of the drive w ith the same drive letter as the one on w hich the new storage
space w as added on the scene data server (ie: C:)
18. Right-click on the files list and select Paste.
19. W hen prompted, grant administrator permission to move the shortcut.
There is now a shortcut pointing to the new scene data storage space on the database server,
allow ing it to connect to this storage space and create and manage scenes inside it.

How to add the new storage space to the list of storage spaces used by Harmony andControl Center
1. Open the Start menu and, in the Programs list, select Toon BoomHarmony 22 [Edition] > Tools >Configuration Editor.
2. W hen prompted, allow Configuration Editor to make changes to your device.
3. Open the Manager.conf tab.
4. Scroll dow n to the bottom. There should be a line starting w ith scene_dir_pattern: follow ed by
the path to the scene data directories used by your server, except for the one you just created. For
example, if the server only had a scene data storage named usadata000, the line w ould be as
follow s:
scene_dir_pattern:/usadata000

5. After the last scene data storage space listed on the scene_dir_pattern line, add a space,follow ed by a slash and the name of the new scene data storage space. For example, if you areadding a scene data storage space named usadata001 and located at the root of your storage
device, you should add it at the end of the line, like so:63

Chapter 2: Harmony Server

scene_dir_pattern:/usadata000 /usadata001

IMPORTANT
Even on W indow s, the path to a scene data directory in Manager.conf must:l

Use forw ard slashes (/) as separators, not backw ard slashes (\).

lStart w ith a forw ard slash, not a drive letter. For example, instead of
C:\usadata001, type /usadata001.

l

Not include the .lnk extension of the shortcut file. If you are adding
C:\usadata001.lnk, simply put /usadata001.

TIP
You can also add * w ildcards in the folder names. For example, this w ill include allscene data directories at the root of your storage device w ith a name starting w ith
usadata:scene_dir_pattern:/usadata* /USADATA*

64

Harmony 22 Installation Guide

Configuring a W indows Database Server to have a Static IP Address
It is common to configure server machines to have a static IP. This avoids having to rely on DNS resolution tofind the server w hen its IP address changes, and it also allow s you to associate the hostname to the server's
static IP address on the machine to skip DNS resolution altogether, increasing netw ork performance.
If your machine is currently connected to a DHCP server that dynamically assigns IP addresses, you canconfigure your machine to permanently use its current IP address. To do this, you can start by making note of
the information for your current netw ork connection, then using these parameters for a permanent IP address.

How to obtain the information about your current connection
1. Open Command Prompt and enter the follow ing command:.
> ipconfig /allThis w ill output information about your current connection:
Windows IP Configuration
Host Name . . . . . . . . . . . . : <hostname>Primary Dns Suffix . . . . . . . : <domain name>
Node Type . . . . . . . . . . . . : Peer-Peer
IP Routing Enabled. . . . . . . . : No
WINS Proxy Enabled. . . . . . . . : No
DNS Suffix Search List. . . . . . : <domaine names>
Ethernet adapter Ethernet:
Connection-specific DNS Suffix . : <domain name>
Description . . . . . . . . . . . : <adapter name>
Physical Address. . . . . . . . . : <MAC address>
DHCP Enabled. . . . . . . . . . . : Yes
Autoconfiguration Enabled . . . . : Yes
Link-local IPv6 Address . . . . . : <IPv6 address>
IPv4 Address. . . . . . . . . . . : <IPv4 address>
Subnet Mask . . . . . . . . . . . : <subnet mask>
Lease Obtained. . . . . . . . . . : <date of lease>
Lease Expires . . . . . . . . . . : <date of expiration>
Default Gateway . . . . . . . . . : <default gateway>
DHCP Server . . . . . . . . . . . : <DHCP server address>
DHCPv6 IAID . . . . . . . . . . . : <DHCPv6 IAID>
DHCPv6 Client DUID. . . . . . . . : <DHCPv6 Client DUID>
DNS Servers . . . . . . . . . . . : <DNS server addresses>
Primary WINS Server . . . . . . . : <WINS server address>
NetBIOS over Tcpip. . . . . . . . : Enabled

65

Chapter 2: Harmony Server

2. In the output, under Ethernet adapter Ethernet, make note of the follow ing data:l

The domains in the DNS Suffix Search Listl

The IPv4 Addressl

The Subnet Maskl

The Default Gateway addressl

The addresses for the DNS Servers

How to configure a W indows server to use a static IP
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. Click View network status and tasks.
3. On the top-left corner of the Netw ork and Sharing Center, select Change adapter settings.

4. Right-click on the netw ork adapter used by your machine to connect to your local netw ork, thenselect Properties.

66Harmony 22 Installation Guide

The Local Area Connection Properties dialog appears.

5. In the items list, select Internet Protocol Version 4 (TCP/IPv4).
6. Click on the Properties button under the list.
The Internet Protocol Version 4 (TCP/IPv4) Properties dialog box opens.

7. Select the Use the following IP address option.
8. In the IP Address field, enter the IPv4 Address you obtained in earlier.

67

Chapter 2: Harmony Server

9. In the Subnet mask field, enter the Subnet mask you obtained earlier.
10. In the Default gateway field, enter the Default gateway address you obtained earlier.
11. Select the Use the following DNS server addresses option.
12. In the Preferred DNS server field, enter the DNS Servers address obtained earlier.
13. If a second DNS server w as listed by ipconfig, type it in the Alternate DNS server field. Otherw ise,leave this field empty.
14. Click on Advanced.
The Advanced TCP/IP Settings dialog opens.
15. Select the DNS tab.

16. Select the Append these DNS suffixes (in order): option.
17. For each DNS Suffix obtained earlier, click on Add, then type in the suffix. Add the suffixes in theorder in w hich there w ere listed.
18. Click on OK.
19. Click on OK in the Internet Protocol Version 4 (TCP/IPv4) Properties dialog.
20. Click on OK in the Ethernet Properties dialog.

68Harmony 22 Installation Guide

Looking Up the Database Server Log on W indows
In order to troubleshoot problems w ith the Harmony database server, you can look through its log. This isdone differently depending on w hether you installed the database server as a W indow s service using
Configuration W izard or using Service Launcher.

How to check the log for the database server service
1. Open an Explorer w indow .
2. Brow se to the follow ing location:
C:\ProgramData\Toon Boom Animation\Toon Boom Harmony
3. Right-click on tbdbserver.log and select Open with > Notepad.

How to check the log for the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

69

Chapter 2: Harmony Server

Launching the Database Server Manually on W indows
You can start the database server directly from a command line. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems. You can view the output of the server
directly in the command line as it launches and handles requests.

How to start the database server manually on W indows
1. In a command line, enter the follow ing command:> C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\win64\bin\tbdbserver.exe

70Harmony 22 Installation Guide

How to Stop and Restart the Database Server on W indows
If you installed the database server as a W indow s service using Configuration W izard, you can stop it andrestart it using the Harmony Control Panel or the W indow s Services control panel. If you installed it using
Service Launcher, you can stop it and restart it manually in Service Launcher.

How to stop and restart the database server service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- tbdbserver.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. W hen you are ready to start the server again, click on Start.

How to stop and restart the database server service using the W indows Services
control panel
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, navigate to System and Security > Administrative Tools.
3. Double-click on Services.

71

Chapter 2: Harmony Server

4. Scroll-dow n to HarmonyStarter0- tbdbserver.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

5. Right-click on the service and select Stop.
6. W hen you are ready to start the server again, right-click on it and select Start.

How to stop and restart the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

72Harmony 22 Installation Guide

Pausing and Resuming the Database Server on W indows
If you need to perform maintenance or updates on a Harmony server, you can pause it instead of stopping itcompletely.
Users w ho attempt to save a scene w hile the server is paused w ill receive a w arning message. The server w illqueue the save and commit the changes w hen the server is resumed.

How to pause the database server
1. In a command prompt, enter the follow ing command:> C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\win64\bin\dbu -p

How to check pause status of the database server
1. In a command prompt, enter the follow ing command:> C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\win64\bin\dbu -P

How to resume the database server
1. In a command prompt, enter the follow ing command:> C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\win64\bin\dbu -res

73

Chapter 2: Harmony Server

Uninstalling the Database Server on W indows
If you installed the database server as a W indow s service using Configuration W izard, you can uninstall it
using the Harmony Control Panel or the W indow s Services control panel. If you installed it using Service
Launcher, you can uninstall it in Service Launcher.

How to uninstall the database server service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- tbdbserver.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on Remove.
The database server service w ill stop and w ill no longer launch on boot.
6. Close the Control Panel.

How to uninstall the database server service using the W indows Services control
panel
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, navigate to System and Security > Administrative Tools.
3. Double-click on Services.

74

Harmony 22 Installation Guide

4. Scroll-dow n to HarmonyStarter0- tbdbserver.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

5. Double-click on the service to open its Properties dialog.
6. In the Startup type drop-dow n, select Disabled.
7. Click on OK.
From that point on, the database server service w ill no longer launch on boot.

How to uninstall the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

75

Chapter 2: Harmony Server

Database Server Installation on macOSOn macOS, you can create a database server by using the Configuration Assistant. The creation of the server isdone in tw o separate steps: The creation of the server's file structure, and the installation of the databaseserver daemon.

NOTES
l

Although the traditional w ay of creating a Harmony Server database is to create the databasefolders at the root of the filesystem on the server, and to mount these folders as netw ork
shares at the root of the filesystem on the clients, this is no longer possible as of macOS 10.15(Catalina). Hence, if your netw ork environment includes machines that use macOS 10.15(Catalina) or later, the topics in this section w ill instruct you to create and mount the databasefolders in /Systems/Volumes/Data and to use shortcuts.conf to configure Harmony tofind the database folders in this location. For more information about shortcuts.conf, see Aboutthe Location of Mount Points on macOS on page 185.

l

If you upgraded a machine from an older version of macOS to macOS 10.15 (Catalina) or later,
any file or folder you created in the root folder (/) w ill be automatically moved to/Users/Shared/Relocated Items.

76Harmony 22 Installation Guide

Setting the Server Hostname on macOS
By default, unless your macOS server is configured to w ork w ith a domain name, macOS w ill append thesuffix .local to its chosen hostname. The configuration tools for Harmony w ill include this suffix w hen
registering the machine's hostname in its configuration.
This can cause a problem w hen w orking in a mixed platform environment, as only machines running on
macOS can communicate w ith your machine using the hostname w ith the .local suffix. Machines running
W indow s or GNU/Linux w ill only be able to communicate w ith your macOS machine using its chosen
hostname, w ithout the .local suffix.
To remedy this, you can manually override the machine's hostname and remove its suffix. This w ay, theconfiguration tools for Harmony and the machines trying to communicate w ith your macOS machine w ill use
the hostname w ithout a suffix.

NOTE
You should only follow this procedure if you do not intend to configure the machines in yournetw ork to w ork w ith a domain name, as macOS w ill not append the suffix .local to thehostname of computers connected through a domain.

How to manually override the hostname on macOS and remove its .local suffix
1. In a terminal, obtain your current machine's hostname, as understood by macOS, w ith the follow ing
command:$ scutil --get HostName
2. If the result is the hostname you chose for your machine follow ed by the suffix .local, override
this by typing the follow ing command, w here <hostname> is the hostname you chose for yourmachine, w ithout the suffix .local:$ sudo scutil --set HostName <hostname>
3. Restart your machine.

77Chapter 2: Harmony Server

Creating a Harmony Database on macOSThe first step to creating a Harmony database server is to create the database's file structure on the machinethat w ill be used as the server.
Depending on your version of macOS, you can proceed w ith the traditional method, w hich is to create them at
the root folder (/) of your filesystem, or in /System/Volumes/Data. This is because macOS 10.15 (Catalina)
and later versions do not allow users to create files and folder in the root folder (/).

How to create a Harmony database on macOS Catalina (10.15) and later
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
3. In the W elcome screen, check the Create a new Toon Boom Harmony database and uncheck all
the other options.
4. Click Continue.
The Create Harmony Database dialog w ill appear. In this dialog, you can configure the options foryour database server.

NOTE
If the Hostname field displays a value that ends w ith .local, this may mean that yourmachine’s hostname needs to be configured—see Setting the Server Hostname on
macOS on page 77.

5. In the Database Path field, type in /System/Volumes/Data/USA_DB.
6. Leave the Create an empty Harmony File System (/USADATA) option unchecked. On macOS
Catalina (10.15) and later, you must create those manually.
7. Click on Create.
8. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
9. If you w ant to create a scene data storage space on this server, open a Terminal, then type in thefollow ing command:$ sudo mkdir -p 777 /System/Volumes/Data/usadata000
The database's base file structure is now created. If you have opted to not create a scene data
storage space, see Creating a Scene Data Storage Server on macOS on page 100 to create astorage space for the scenes on your Harmony database.

78

Harmony 22 Installation Guide

10. Now , to configure Harmony to look for the database files in /System/Volumes/Data, w e must
edit its shortcuts.conf configuration file. In a terminal, enter the follow ing command:$ vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/shortcuts.conf"
11. At the top of the file, type the follow ing header line:
shortcut_list :12. Under shortcut_list :, add a line specifying the location of the mount point for each of themounted netw ork shares in the follow ing format:/<folder name> /<full path to folder>

For example, for USA_DB, you w ould add the follow ing line:/USA_DB /System/Volumes/Data/USA_DB

If you created a scene data storage space named usadata000 on your server, add the follow ing
line:/usadata000 /System/Volumes/Data/usadata000

13. Save and quit.

How to create a Harmony database on macOS 10.14 (Mojave) and earlier
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
3. In the W elcome screen, check the Create a new Toon Boom Harmony database and uncheck all
the other options.
4. In the Create Harmony Database dialog, you can configure the options for your database server.

79

Chapter 2: Harmony Server

NOTE
If the Hostname field displays a value that ends w ith .local, this may mean that yourmachine’s hostname needs to be configured—see Setting the Server Hostname on
macOS on page 77.

5. Click on Create.
6. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
7. If you w ant to create a scene data storage space on this server, open a Terminal, then type in thefollow ing command:$ sudo mkdir -p 777 /usadata000
The database's base file structure is now created. If you have opted to not create a scene data
storage space, see Creating a Scene Data Storage Server on macOS on page 100 to create astorage space for the scenes on your Harmony database.

80Harmony 22 Installation Guide

Installing the Database Server Daemon on macOS
Once you have created a database file structure, you must also enable the database server daemon to allow
Harmony to connect to the database. This daemon runs through the user usabatch, so this user must be
created prior to installing the daemon.

NOTE
The follow ing steps indicate how to make the database server daemon launch on boot, via theuser usabatch, w ho w ill have administrator privileges. If you prefer, you can make the databaseserver launch on log-in as the logged-in user. For more information, see Running the Database
Server on Log-In on macOS on page 83.

How to create the user usabatch on macOS
1. Open the Apple menu and select System Preferences.
2. Click on Users and Groups.
3. In the bottom-left corner of the Users & Groups dialog, click on the lock icon labeled Click the lockto make changes to get administrator permissions.
4. Enter the username and passw ord of an account w ith administrator privileges.
5. Click on the + button at the bottom of the user list.
The user creation panel appears.
6. In the New Account drop-dow n, select Administrator.
7. In the Full Name and Account Name fields, enter usabatch.
8. Give the user a passw ord.
9. Click on Create User.

How to install the database server daemon on macOS
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
1. In the W elcome screen, check the Create the Startup Items option and uncheck all other options.
2. Click on Continue.

81Chapter 2: Harmony Server

3. Check the Create Database Server Startup Item option and uncheck all other options.
4. Click on Create.
5. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
The database server daemon is now installed and w ill start running. At this point, you should
already be able to run Control Center from this machine, log-in w ith the default user usabatchand create scenes and users.

82

Harmony 22 Installation Guide

Running the Database Server on Log- In on macOSThe traditional w ay of configuring the database server is by using the Configuration Assistant to install it as a
daemon. This makes the database server launch immediately on boot, as user usabatch.
Using Service Launcher, it is possible to configure your database server to only launch its database server
service as the logged-in user. This means the database w ill only be accessible if the user configured to run it issigned in. Although this may seem impractical, it may be preferable for security reasons, mainly that thelogged-in user does not need to have administrator privileges to run services through Service Launcher.
If you have already installed the database server daemon using Configuration Assistant, you w ill need todisable the daemon first to avoid launching tw o instances of the database server.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the database server daemon
1. In a terminal, type in the follow ing command:$ sudo launchctl unload -w/Library/LaunchDaemons/com.toonboom.DatabaseServer.plist
The database server daemon w ill stop and w ill no longer launch on boot.

How to configure the database server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

83Chapter 2: Harmony Server

2. Do one of the follow ing:l

If Service Launcher is not running, follow these steps to launch it:a. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] anddouble-click Harmony [Edition].
The main Harmony application launches.
b. In the top menu, select Harmony [Edition] > Tools > Service Launcher.
l

If Service Launcher is already running, click on its iconin the menu bar.

The Service Launcher application w indow appears.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the Database Server tab.
5. Click on Launch to verify that the database server launches successfully through Service Launcher.
6. Check the Launch when Service Launcher starts option.
7. In the top menu, select Server > Save All Settings.
From now on, the database server w ill launch through Service Launcher w hen you log in.

84Harmony 22 Installation Guide

Sharing the Harmony Database Files Using NFS on macOS
Once you have a database file structure and the Harmony database server daemon, you can access the
database from the machine on w hich it w as created. To allow other client machines on your netw ork to accessthe database, you must share its folders using NFS.

NOTEThis procedure w ill only allow macOS and GNU/Linux based clients to access the database. If you
w ant W indow s clients to be able to connect to your Harmony server, see About Supporting
W indow s Clients for macOS Servers on page 87.

How to share the database files using the NFS protocol on macOS 10.15 (Catalina)
and later
1. In a terminal, enter the follow ing command:$ sudo vi /etc/exports
2. Add the follow ing line to allow clients to access the database files:l

On macOS Catalina (10.15) and later:/System/Volumes/Data/USA_DB -maproot=nobodylOn macOS Mojave (10.14) and earlier:/USA_DB -maproot=nobody

3. If your database server also has a scene data storage space, add a line w ith a similar syntax toshare it.
l

On macOS Catalina (10.15) and later:/System/Volumes/Data/usadata000 -maproot=nobodylOn macOS Mojave (10.14) and earlier:/usadata000 -maproot=nobody

4. Save and exit.
5. Verify that the NFS exports are properly configured w ith the follow ing command:$ sudo nfsd checkexports
The command w ill not return anything if the exports file is properly configured.
6. Make sure the NFS sharing service is enabled w ith the follow ing command:$ sudo nfsd enable85

Chapter 2: Harmony Server

7. If the service w as already started, terminate it to force it to load your configuration changes.
$ sudo kill -1 `cat /var/run/mountd.pid`

NOTE
The back quote (`) character is located at the top-left of the macOS keyboard on thesame key as the tilde (~) character. Or simply reboot the computer.

8. Verify that the folders are shared:$ showmount -e
The command should output a line for each directory you are sharing using the NFS protocol. For
example:l

On macOS Catalina (10.15) and later:/System/Volumes/Data/USA_DB Everyone/System/Volumes/Data/usadata000 EveryonelOn macOS Mojave (10.14) and earlier:/USA_DB Everyone/usadata000 Everyone

You should now be able to mount the shared folders from any macOS or GNU/Linux-based
machine on your local netw ork.

86

Harmony 22 Installation Guide

About Supporting W indows Clients for macOS Servers
A macOS server can natively handle requests from macOS and GNU/Linux clients. How ever, in order to allow
W indow s based clients to connect to the server, extra steps must be follow ed:l

The Link Server daemon must be installed. This allow s W indow s clients to create symbolic links onyour macOS server.

lYour database files must be shared via the Samba protocol, w hich is used by W indow s clients to accessthe database.

l

The server.ini file must be filled w ith information on your database server and its scene data storage
spaces. This allow s Configuration W izard to configure W indow s clients automatically.

Installing the Link Server Daemon on macOS

88

Running the Link Server on Log- In on macOS

89

Sharing the Harmony Database Files Using Samba on macOS

91

Configuring a macOS Database Server for W indows Clients

98

87

Chapter 2: Harmony Server

Installing the Link Server Daemon on macOSIf you installed the database server daemon using Configuration Assistant and w ant your macOS based server
to support W indow s clients, you must also install the link server daemon.

How to install the database server daemon on macOS
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
3. In the W elcome screen, check the Create the Startup Items option and uncheck all other options.
4. Click on Continue.
5. Check the Create Link Server Startup Item option and uncheck all other options.
6. Click on Create.
7. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
The link server daemon is now installed and should start immediately.

88Harmony 22 Installation Guide

Running the Link Server on Log- In on macOSIf you configured your database server to launch using Service Launcher, you w ill also w ant the Link Server tolaunch using service launcher, so that it launches in the same circumstances and environment. For more
information on running the database server w ith Service Launcher, see Running the Database Server on LogIn on macOS on page 83.
If you have already installed the link server daemon using Configuration Assistant, you w ill need to disable thedaemon first to avoid launching tw o instances of the linkserver.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the link server daemon
1. In a terminal, type in the follow ing command:$ sudo launchctl unload -w/Library/LaunchDaemons/com.toonboom.LinkServer.plist

How to configure the link server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill launch the link server.

NOTE
This user w ill need to be logged in for the link server to be running. The user does notneed to have administrator privileges.

2. Do one of the follow ing:l

If Service Launcher is not running, follow these steps to launch it:a. In Finder, proceed to Applications >double-click Harmony [Edition].

89

Toon Boom Harmony 22 [Edition] andChapter 2: Harmony Server

The main Harmony application launches.
b. In the top menu, select Harmony [Edition] > Tools > Service Launcher.
l

If Service Launcher is already running, click on its iconin the menu bar.

The Service Launcher application w indow appears.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the Link tab.
5. Click on Launch to verify that the Link Server launches successfully through Service Launcher.
6. Check the Launch when Service Launcher starts option.
7. In the top menu, select Server > Save All Settings.
From now on, the link server w ill launch through Service Launcher w hen you log in.

90

Harmony 22 Installation Guide

Sharing the Harmony Database Files Using Samba on macOS
Sharing the database folders on a macOS server via Samba is only required if you intend to have clientsrunning W indow s, as W indow s does not natively support connecting to NFS shares. How ever, theimplementation of Samba that is natively bundled w ith macOS does not w ork w ith Harmony Server.
Therefore, to make your macOS-based Harmony database server accessible from W indow s clients, you must
disable the implementation of Samba that is bundled w ith macOS, and then install and configure the open
source implementation of Samba instead. The most straightforw ard w ay is to install the open source
implementation of Samba is by using the MacPorts package manager.
After that, you w ill need to:
1. Configure a Samba share for each database and scene data folder on your server, as w ell as for the
Harmony installation itself.
2. Creating a Samba username and passw ord, w hich w ill be needed to access the Samba shares from aremote computer.
3. Creating and activating launch daemons for Samba, so that it automatically runs in the backgroundw hen the computer is running.

IMPORTANT
Since this procedure requires installing and configuring a third party softw are, consider these
instructions as indicative only. Using Samba to connect to a macOS based Harmony server cannot
be guaranteed to succeed and, even if it succeeds, it is alw ays possible that a future update or
upgrade of macOS makes this method no longer w ork.

How to disable the native Samba file sharing protocol on macOS
1. Open the Apple menu and select System Preferences.
2. Click on Sharing.
3. In the list to the left, if File Sharing is unchecked, then SMB is implicitly disabled. If File Sharing ischecked, select it.
4. Click on Options.
5. Make sure that Share files and folders using SMB is unchecked.
6. Click on Done.
7. Close the Sharing panel.

91

Chapter 2: Harmony Server

How to install the open source implementation of Samba on macOS
1. First, make sure MacPorts is installed on your machine. To dow nload and install MacPorts, go tohttps://w w w .macports.org.
2. Open a terminal and enter the follow ing command to install the Xcode command line utilities,
w hich are required by MacPorts to compile Samba:$ sudo xcode-select --install
3. A dialog w ill appear. Follow the instructions to confirm and proceed w ith the installation of the
Xcode command line utilities.
4. In the terminal, type in the follow ing command to install Samba using MacPorts:$ sudo port install samba3
5. Confirm the installation of samba3 and its dependencies.
Once the installation is done, the binaries and configuration files for Samba w ill be installed in/opt/local.

NOTES
l

By default, this implementation of Sambe is not configured to run in the backgroundas a service. The steps below w ill help you configure Samba and make it run as a
background service that w ill launch on boot.

l

The Samba binary directories w ill not be in your $PATH environment variable bydefault. Hence, unless you manually add the directories /opt/local/bin and/opt/local/sbin to your $PATH environment variable, the steps to configuring
and testing Samba w ill require you to type the full path to each binary you run in theterminal.

How to configuring the Samba shares for your Harmony Server database on macOS
1. In a terminal, open the Samba configuration file to configure Samba and add your database
directories as Samba shares:$ vi /opt/local/etc/samba3/smb.conf
2. Add the follow ing block to the file to set the global options for the Samba server:[global]encrypt passwords = yes
blocking locks = nooplocks = no92

Harmony 22 Installation Guide

level2 oplocks = nofollow symlinks = yes
unix extensions = nowide links = yes

3. Add the follow ing to make your Harmony configuration files and binaries accessible to the client:[usa]
comment = Harmony Binaries and Configuration
browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /Applications/Toon Boom Harmony 22 [Edition]/Harmony [Edition].app/Contents/tba

4. Add the follow ing to make your Harmony Server database files accessible to the client:l

On macOS 10.15 (Catalina) and later:[USA_DB]
comment = Harmony Databasebrowseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /System/Volumes/Data/USA_DBl

On macOS 10.14 (Mojave) and earlier:[USA_DB]
comment = Harmony Databasebrowseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /USA_DB

5. If your server has a scene data folder, add a similar netw ork share configuration to make themaccessible to the client as w ell, w here <scene data folder name> is the name of that folder,
and ### is the number of that folder.

93

Chapter 2: Harmony Serverl

On macOS 10.15 (Catalina) and later:[<scene data folder name>]comment = Harmony Scene Data ###browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /System/Volumes/Data/<scene data folder name>For example, if you have a scene data folder named usadata000, you w ould need to add
the follow ing:
[usadata000]
comment = Harmony Scene Data 000
browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /System/Volumes/Data/usadata000l

On macOS 10.14 (Mojave) and earlier:[<scene data folder name>]comment = Harmony Scene Data ###browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /<scene data folder name>.For example, if you have a scene data folder named usadata000, you w ould need to add
the follow ing:
[usadata000]
comment = Harmony Scene Data 000
browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /usadata000

6. Save and quit.

94

Harmony 22 Installation Guide

7. Verify that Samba understands the parameters in its configuration file w ith the follow ing
command:$ /opt/local/bin/testparm

How to create a Samba username and password
1. A local user must be added to the list of users w ith access to the Samba shares. To do this, type in
the follow ing command, w here <username> is replaced by the name of a user that has access tothis computer:$ sudo /opt/local/bin/smbpasswd -a <username>For example, to give access to user usabatch, type in the follow ing command:$ sudo /opt/local/bin/smbpasswd -a usabatch
You w ill be prompted to assign a passw ord to this new user, then to confirm it. This username andpassw ord w ill be used to connect to the Samba shares.

NOTES
l

The user you are adding to the list of Samba users must already exist as a regularmacOS user account that has access to this computer.

l

On W indow s clients, w hen using the Configuration W izard to configure Harmony
database clients, you must enter this user's username and passw ord in order to beable to connect to the database shares.

How to launch Samba as a background service
1. Enter the follow ing command to create the Samba launch daemon:$ sudo vi /Library/LaunchDaemons/org.samba.smdb.plist
2. Copy and paste the follow ing text in the editor:<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/Prope<plist version="1.0"><dict><key>Label</key><string>org.samba.smbd</string><key>OnDemand</key><true/><key>ProgramArguments</key>95

Chapter 2: Harmony Server<array><string>/opt/local/sbin/smbd</string><string>-Fs</string><string>/opt/local/etc/samba3/smb.conf</string></array><key>RunAtLoad</key><true/><key>ServiceDescription</key><string>samba</string></dict></plist>

3. Save and quit.
4. Enter the follow ing command to create the NetBIOS name server daemon:$ sudo vi /Library/LaunchDaemons/org.samba.nmdb.plist
5. Copy and paste the follow ing text in the editor:<?xml version="1.0" encoding="UTF-8"?><!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/Prope<plist version="1.0"><dict><key>Label</key><string>org.samba.nmbd</string><key>OnDemand</key><false/><key>ProgramArguments</key><array><string>/opt/local/sbin/nmbd</string><string>-F</string></array><key>RunAtLoad</key><true/><key>ServiceDescription</key><string>netbios</string></dict></plist>

6. Save and quit.
7. For security reasons, the filemode for the launch daemons must be set so that only administrators
can edit them, otherw ise macOS w ill ignore them:$ sudo chmod 644 /Library/LaunchDaemons/org.samba.smdb.plist$ sudo chmod 644 /Library/LaunchDaemons/org.samba.nmdb.plist
8. Now enable both services:$ sudo launchctl load /Library/LaunchDaemons/org.samba.smdb.plist$ sudo launchctl load /Library/LaunchDaemons/org.samba.nmdb.plist

96

Harmony 22 Installation Guide

At this point, your Samba server should be fully operational and your netw ork shares should beaccessible from other computers on your local netw ork.

How to test that the Samba configuration is working
1. You can test that access to your server using Samba is w orking by trying to get a list of yourserver’s Samba shares from another computer, using the method for that computer’s operating
system:l

On macOS: By opening Finder, then selecting Go > Connect to Server in the top menu, andtyping smb://<server name> in the address field.

l

On W indows: By typing opening an Explorer w indow and typing \\<server name> in theaddress bar.

In both cases, <server name> is the hostname of your server.
2. W hen prompted for a username and passw ord, type in the username and passw ord you enteredw hen you created a Samba user in the previous steps.
If you have sucessfully authenticated, you should then see a list of all the Samba shares you
configured (i.e.: usa, USA_DB, usadata000, etc.).
3. Try to select one of the available netw ork shares, and see if you can access it.

97Chapter 2: Harmony Server

Configuring a macOS Database Server for W indows Clients
In order to allow W indow s clients to connect to your server using the Configuration W izard, you must fill inthe server.ini configuration file, w hich is located in the etc subfolder of the Harmony installation package. This
file w ill provide Configuration W izard w ith information on the server as w ell as of each scene data server it isconnected to.

How to configure the server.ini file on macOS
1. In a terminal, type in the follow ing command:$ sudo vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/server.ini"
2. In server.ini, type in the information for the database server as w ell as the directory name andhostname of every scene data server in your netw ork, like in the follow ing example:[WizardConfig]
ServerName=<server name>InstallationDrive=C
UsaShare=<harmony share name>
UsadbDrive=C
UsadbShare=<database share name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<server name>: The host name of the Harmony database server.

l<harmony share name>: The name of the share that gives access to the Harmony binaries
and configuration files. By default, this share is named usa.

l<database share name>: The name of the share that gives access to the database files.
By default, this share is named USA_DB.

For example, if your database server is called harmonyserver, your Harmony installation is sharedunder the share name usa and your Harmony database is shared under the share name USA_DB,
this w ould be the proper configuration for this server:[WizardConfig]
ServerName=harmonyserver
InstallationDrive=C
UsaShare=usa
UsadbDrive=C
UsadbShare=USA_DB

98

Harmony 22 Installation Guide

3. Under the line starting w ith UsadbShare, enter information about each scene data storage spaceused by your Harmony database, in the follow ing format:
FileSystem<file system number>=C <share name> <server name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<file system number>: The zero-based index of the scene data storage space. For
example, the first scene data storage space for your database should be named
FileSystem0 and the second one, FileSystem1.

l<share name>: The name of the share containing the scene data. Usually, this share iseither named USADATA or usadata, and its name may be follow ed by a zero-padded, zerobased number indicating the index of the scene data storage space. For example, the firstscene data storage space could be named USADATA, usadata000, usadata001, etc.

l<server name>: The host name of the scene data server. If the scene data storage space ishosted on the same machine as the database, then this host name is the same as the hostname for the database. Otherw ise, you must specify the name of the machine on w hich thescene data storage space is located.

For example, if this is the first scene data storage space for your database, it is hosted on acomputer named dataserver and its name is usadata000, the appropriate configuration for thisw ould be as follow s:
FileSystem0=C usadata000 dataserver

IMPORTANTThe variable names and share names in server.ini are case sensitive.

NOTE
server.ini also specifies the drive letter on w hich the softw are, the database files andscene data files are stored. Since w e are configuring a UNIX-based server, there is no actual
drive letter involved. Hence, w e are using the drive letter C as a placeholder so as to respect
the expected format of the server.ini configuration file, but the value of these parameters
is not relevant and w ill not affect your configuration.

99

Chapter 2: Harmony Server

Creating a Scene Data Storage Server on macOSYou can create additional scene data storage spaces for your Harmony database on machines. The databaseserver w ill connect to these machines to transmit scene data to the clients, allow ing you to expand the storage
capacity of your database.
Creating a scene data storage space for your Harmony database requires follow ing these steps:
1. Creating a folder named usadata follow ed by the index number of the storage space at the root of themachine.
2. Sharing the folder via NFS and, if W indow s clients must be supported, via Samba as w ell.
3. Mounting this folder on the database server.
4. If W indow s clients must be supported, adding this storage server to the server.ini configuration file.

How to create a scene data storage space on macOS Catalina (10.15) and later
1. In a terminal, enter the follow ing command, w here ### is the padded, zero-based index of thestorage space you are creating, replace ### w ith 001:
$ sudo mkdir -m 777 /Volumes/System/Data/usadata###
A folder in w hich scene data w ill be stored is created.

How to create a scene data storage space on macOS on macOS Mojave (10.14) andearlier
1. In a terminal, enter the follow ing command, w here ### is the padded, zero-based index of thestorage space you are creating, replace ### w ith 001:
$ sudo mkdir -m 777 /usadata###
A folder in w hich scene data w ill be stored is created at the root of the filesystem.

How to share the scene data storage space on macOS
1. Sharing a scene data storage space is done the exact same w ay as sharing the server's databasefile system.
l

To share the scene data storage space for macOS and GNU/Linux based clients, see Sharing
the Harmony Database Files Using NFS on macOS on page 85.

100Harmony 22 Installation Guidel

To share the scene data storage space for W indow s clients, see Sharing the Harmony
Database Files Using Samba on macOS on page 91.

Once this is done, you should already be able to mount the new scene data storage space on the
database server as w ell as on clients.

How to mount the new scene data storage space on a macOS database server onmacOS Catalina (10.15)
1. First, you should set a permissive file permission mask on the server machine. This w ill make it sofiles created by the database server on the scene data server w ill have the proper permissions toallow any user to edit them. To do this, see Setting the User File Creation Permission Mask on
macOS on page 183.
2. In a terminal, create a folder in /mnt in w hich the new scene data storage space w ill be mounted
w ith the follow ing command, w here <foldername> is the name of the scene data directory you
created on the scene data server:$ sudo mkdir -m 777 /System/Volumes/Data/mnt/<share name>
3. Then, create a symbolic link from the root of the filesystem (/) to the mount point:$ sudo ln -s /System/Volumes/Data/mnt/<share name>/System/Volumes/Data/<share name>
4. Open the NFS mount points configuration file by typing the follow ing command:$ sudo vi /etc/auto_nfs
5. In the filesystem table, add the follow ing line, replacing <servername> w ith the name of thescene data server and <foldername> w ith the name of the scene data directory you created on
this scene data server:/System/Volumes/Data/mnt/<share name> -fstype=nfs,rw,soft,intr,resvport nfs://<server name>:/<6. Save and quit.
7. Attempt to mount the entries of the filesystem table:$ sudo mount -a
8. To make sure that it w orked, try creating a file in the new scene data storage, and verify that it'svisible from both machines. To do this:l

On one machine, enter the follow ing command:$ touch /System/Volumes/Data/<share name>/testfile

101

Chapter 2: Harmony Serverl

On the other machine, enter the follow ing command to verify that testfile is present$ ls /System/Volumes/Data/<share name>/

9. Now , to configure Harmony to look for the database files in /System/Volumes/Data, w e must
edit its shortcuts.conf configuration file. In a terminal, enter the follow ing command:$ vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/shortcuts.conf"
10. Under shortcut_list :, add a line specifying the location of the mount point for each of themounted netw ork shares in the follow ing format:/<share name> /<full path to symlink to mount point>

For example, if you are adding a scene data space named usadata001, add the follow ing line:/usadata001 /System/Volumes/Data/usadata001

11. Save and quit

How to mount the new scene data storage space on a macOS database server onmacOS Mojave (10.14) or earlier
1. First, you should set a permissive file permission mask on the server machine. This w ill make it sofiles created by the database server on the scene data server w ill have the proper permissions toallow any user to edit them. To do this, see Setting the User File Creation Permission Mask on
macOS on page 183.
2. In a terminal, create a folder in /mnt in w hich the new scene data storage space w ill be mounted
w ith the follow ing command, w here <foldername> is the name of the scene data directory you
created on the scene data server:$ sudo mkdir -m 777 /mnt/<share name>
3. Then, create a symbolic link from the root of the filesystem (/) to the mount point:$ sudo ln -s /mnt/<share name> /<share name>
4. Open the NFS mount points configuration file by typing the follow ing command:$ sudo vi /etc/auto_nfs
5. In the filesystem table, add the follow ing line, replacing <servername> w ith the name of thescene data server and <foldername> w ith the name of the scene data directory you created on
this scene data server:

102

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

6. Save and quit.
7. Attempt to mount the entries of the filesystem table:$ sudo mount -a
8. To make sure that it w orked, try creating a file in the new scene data storage, and verify that it'svisible from both machines. To do this:l

On one machine, enter the follow ing command:$ touch /<share name>/testfilel

On the other machine, enter the follow ing command to verify that testfile is present$ ls /<share name>/

How to add the scene data storage file to the server.ini configuration file
1. In a terminal, type in the follow ing command:$ sudo vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/server.ini"
If the file w as already configured, it most likely contains configuration in the follow ing format:[WizardConfig]
ServerName=<name of Harmony server>
InstallationDrive=C
UsaShare=usa
UsadbDrive=C
UsadbShare=USA_DB
FileSystem0=C usadata000 <name of first scene data server>

2. Under the last line starting w ith FileSystem0 w hich contains information about an existing scene
data storage space, enter the information about your new scene data storage space in thefollow ing format:
FileSystem<file system number>=C <share name> <server name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<file system number>: The zero-based index of the scene data storage space. For
example, the first scene data storage space for your database should be named

103

Chapter 2: Harmony Server

FileSystem0 and the second one, FileSystem1.
l<share name>: The name of the share containing the scene data. Usually, this share iseither named USADATA or usadata, and its name may be follow ed by a zero-padded, zerobased number indicating the index of the scene data storage space. For example, the firstscene data storage space could be named USADATA, usadata000, usadata001, etc.

l<server name>: The host name of the scene data server. If the scene data storage space ishosted on the same machine as the database, then this host name is the same as the hostname for the database. Otherw ise, you must specify the name of the machine on w hich thescene data storage space is located.

For example, if this is your second scene data storage space for your database server, it is hosted
on a computer named newdataserver and is named usadata001, its configuration w ould be as
follow s:
FileSystem1=C usadata001 newdataserver

IMPORTANTThe variable names and share names in server.ini are case sensitive.

NOTE
The first information for a scene data storage space, C, is actually the drive letter on w hich thescene data storage space is located. Since macOS does not use drive letters, there is no drive
letter for this storage space, and w e are only specifying a drive letter to respect the format of
the server.ini configuration file. This value does not have an effect your server
configuration.

104

Harmony 22 Installation Guide

Configuring a macOS Database Server to have a Static IP Address
It is common to configure server machines to have a static IP. This avoids having to rely on DNS resolution tofind the server w hen its IP address changes, and it also allow s you to associate the hostname to the server's
static IP address on the machine to skip DNS resolution altogether, increasing netw ork performance.
If your machine is currently connected to a DHCP server that dynamically assigns IP addresses, you canconfigure your machine to permanently use its current IP address. To do this, you can start by making note of
the information for your current netw ork connection, then using these parameters for a permanent IP address.

How to obtain information about your current connection on macOS
1. Open the Apple menu and select System Preferences.
2. Click on Network.
The Netw ork configuration panel appears.

3. In the list to the left, select Ethernet.
4. In the panel to the right, make note of the follow ing information:l

The IP Addressl

The Subnet Maskl

The Router addressl

The DNS Serverl

The Search Domains

105Chapter 2: Harmony Server

How to configure a macOS server to use a static IP
1. Open the Apple menu and select System Preferences.
2. Click on Network.
3. In the list to the left, select Ethernet.
4. In the Location drop-dow n, select Edit Locations.

5. Click on the + button to add a location, then name it Static.

6. Click on Done.

106

Harmony 22 Installation Guide

7. Click on Advanced.
8. In the TCP/IP tab of the Advanced Netw ork panel, enter the follow ing information:l

Set the IPv4 Address to the IP Address obtained earlier.

l

Set the Subnet Mask to the Subnet Mask obtained earlier.

l

Set the Router address to the Router address obtained earlier.

9. Open the DNS tab.
10. Under the DNS Servers list, click on the + button to add a DNS server. Add each of the DNS Server
addresses obtained earlier.
11. Under the Search Domains list, click on the + button to add a search domain. Add each of thesearch domains obtained earlier.
12. Click on OK.
If your configuration w orks, the Netw ork panel w ill indicate Status: Connected at the top.

107

Chapter 2: Harmony Server

Looking Up the Database Server Log on macOS
In order to troubleshoot problems w ith the Harmony database server, you can look through its log. This isdone differently depending on w hether you installed the database server as a daemon using Configuration
Assistant, or using Service Launcher.
If your server is configured for W indow s clients, you can also check the link server log for issues.

How to check the log for the database server daemon
1. In a terminal, enter the follow ing command:$ less /tmp/com.toonboom.DatabaseServer.log

How to check the log for the link server daemon
1. In a terminal, enter the follow ing command:$ less /tmp/com.toonboom.LinkServer.log

How to check the log for the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

How to check the log for the link server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher
The Service Launcher application opens.
3. Select the Link tab.
4. In the bottom half, select the Log tab.

108

icon.

Harmony 22 Installation Guide

5. Click on the View Complete Log button in the bottom-right corner.

109

Chapter 2: Harmony Server

Launching the Database Server Manually in macOSYou can start the database server directly from a terminal. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems.
If your server needs to handle W indow s clients, you can also launch the link server in a different terminal toensure that both services w ork.
You can view the output of both services directly in the terminal in w hich you launch them as they start andhandle requests.

How to start the database server manually
1. In a terminal, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/tbdbserver"

How to start the link server manually
1. In another terminal, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/Link_srv"

110Harmony 22 Installation Guide

Stopping and Restarting the Database Server on macOSIf you installed the database server as a daemon using the Configuration Assistant, you can stop it and restart
it using the launchctl command line tool. If you installed it using Service Launcher, you can stop it andrestart it manually in Service Launcher.
If you have installed the link server so as to be able to handle W indow s clients, stopping and restarting it may
also be necessary for the intended purpose.

How to stop and restart the database server daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload/Library/LaunchDaemons/com.toonboom.DatabaseServer.plist
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo launchctl load
/Library/LaunchDaemons/com.toonboom.DatabaseServer.plist

How to stop and restart the link server daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload/Library/LaunchDaemons/com.toonboom.LinkServer.plist
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo launchctl load
/Library/LaunchDaemons/com.toonboom.LinkServer.plist

How to stop and restart the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

111

Chapter 2: Harmony Server

How to stop and restart the link server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Link Server tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

112Harmony 22 Installation Guide

Pausing and Resuming the Database Server on macOSIf you need to perform maintenance or updates on a Harmony server, you can pause it instead of stopping itcompletely.
Users w ho attempt to save a scene w hile the server is paused w ill receive a w arning message. The server w illqueue the save and commit the changes w hen the server is resumed.

How to pause the database server
1. In a command prompt, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/dbu" -p

How to check pause status of the database server
1. In a command prompt, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/dbu" -P

How to resume the database server
1. In a command prompt, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/dbu" -res

113

Chapter 2: Harmony Server

Uninstalling the Database Server on macOSIf you installed the database server as a daemon using the Configuraton Assistant, you can uninstall it using
the launchctl command line tool. If you installed it using Service Launcher, you can uninstall it in Service
Launcher.

How to uninstall the database server daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload -w/Library/LaunchDaemons/com.toonboom.DatabaseServer.plist
The daemon w ill no longer launch on boot.
2. If you w ant, you can delete the daemon permanently w ith the follow ing command:$ sudo rm /Library/LaunchDaemons/com.toonboom.DatabaseServer.plist

How to uninstall the link server daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload -w/Library/LaunchDaemons/com.toonboom.LinkServer.plist
The daemon w ill no longer launch on boot.
2. If you w ant, you can delete the daemon permanently w ith the follow ing command:$ sudo rm /Library/LaunchDaemons/com.toonboom.LinkServer.plist

How to uninstall the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

114

Harmony 22 Installation Guide

How to uninstall the link server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Link Server tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

115

Chapter 2: Harmony Server

Database Server Installation on GNU/LinuxOn GNU/Linux, you can create a database server w ith the help of a script that creates the basic database filestructure, then enabling the database server daemon w hich w as created during the installation of Harmony.

116

Harmony 22 Installation Guide

Disabling Security for a Harmony Database Server on GNU/Linux
GNU/Linux comes bundled w ith tw o core security components:l

A firew all (typically either iptables or firewalld), w hich w ill block incoming connections that w ere notspecifically allow ed.

l

SELinux, a kernel security module that enforces access control policies on softw are, files and netw ork
resources.

The default configuration for these components w ill prevent clients from connecting to a Harmony databaseserver. This installation guide provides instructions on how to add security exceptions to these components sothat they do not have to be disabled. How ever, you may prefer to disable them so as to simplify the
installation process or to rule out security components as possible causes w hen troubleshooting an issue.

IMPORTANT
If you choose to disable the firew all and SELinux, it is critical to ensure that your domain has
effective site-w ide security measures to prevent unauthorized access to your database server.

How to disable the firewall on CentOS 6, RedHat Entreprise Linux 6 or other systems
using the iptables service
1. In a terminal, enter the follow ing commands:$ sudo chkconfig iptables off$ sudo service iptables stop

How to disable the firewall on CentOS 7, RedHat Entreprise Linux 7 or other systems
using the firewalld service
1. In a terminal, enter the follow ing commands:$ sudo systemctl disable firewalld$ sudo systemctl stop firewalld

How to disable SELinux
1. In a terminal, enter the follow ing command:$ sudo vi /etc/selinux/config
2. Find the line w ith the follow ing parameter:

117

Chapter 2: Harmony Server

SELINUX=enforcing

3. Replace enforcing w ith disabled:
SELINUX=disabled

IMPORTANT
Double-check to make sure you did not make any typo. An error in the SELinuxconfiguration file may cause GNU/Linux to fail to boot.

4. Save and quit.
5. Reboot to apply the new configuration.

118

Harmony 22 Installation Guide

Creating a Harmony Database on GNU/LinuxThe first step to creating a Harmony database server is to create the database's file structure on the machinethat w ill be used as the server. You can accomplish this by running the create_usa_db script from
Harmony's bin directory.
The basic database file structure is in the USA_DB directory. How ever, this is not w here scene data is stored. If
you w ant the database server to be able to host scene data, you can also create an empty scene data storage
space alongside your database file structure.

NOTE
The follow ing steps only indicate how to create a database file structure using the create_usa_
db script. If you prefer, you can create the database file structure and enable the database server
daemon simultaneously using the Harmony installation script—see Installing the Database Server
Daemon on GNU/Linux on page 120.

How to create a database file structure using the create_usa_db script
1. In a terminal, navigate to the directory in w hich the Harmony binaries w ere installed:$ cd /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin
2. Run the database creation script:$ sudo ./create_usa_db
The script w ill create the basic file structure for a Harmony database in /USA_DB.

How to create a scene data storage space
1. In a terminal, enter the follow ing command:$ sudo mkdir -m 777 /usadata000
A scene data storage directory named usadata000 is now located at the root of your databaseserver's file system.

119

Chapter 2: Harmony Server

Installing the Database Server Daemon on GNU/Linux
Once you have created a database file structure, you must also enable the database server daemon to allow
Harmony to connect to the database. This daemon runs through the user usabatch, so this user must be
created prior to installing the daemon.
The Harmony installer for GNU/Linux alw ays installs daemon scripts on your machine, but does not enable
them by default. Hence, there are tw o approaches to installing the database server daemon:l

By enabling the daemon that w as already installed w ith Harmony using the chkconfig command.

l

By running the Harmony installation script w ith the -d parameter. This w ill also create a database filestructure on your machine if none is present.

This daemon runs through the user usabatch, so this user must be created prior to installing the daemon.

NOTE
The follow ing steps indicate how to make the database server daemon launch on boot, via theuser usabatch. If you prefer, you can make the database server launch on log-in as the logged-in
user. For more information, see Running the Database Server on Log-In on GNU/Linux on page122.

How to create the usabatch user on GNU/Linux
1. In a terminal, enter the follow ing command:$ sudo useradd -m usabatch$ sudo passwd usabatch
2. W hen prompted, enter the passw ord you w ant to assign to the user usabatch, then confirm it.
The user usabatch is now created and can be used to run Harmony daemons.

How to enable the database server daemon on GNU/Linux
1. In a terminal, enter the follow ing command to enable the database server daemon:$ sudo chkconfig toonboom_dbserver on
If the command returns nothing, it succeeded. The database server w ill launch next time you bootthe machine.
2. To launch the database server daemon immediately, run the follow ing command:$ sudo service toonboom_dbserver start
The command w ill report w hether it succeeded or failed.

120

Harmony 22 Installation Guide

How to create a database file structure and enable the database server daemon
simultaneously using the Harmony installation script
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package
4. Run the installer w ith the -d parameter:$ sudo ./install -d
5. W hen prompted, confirm that you w ant to proceed w ith the installation.
The installation script w ill create a database file structure in /USA_DB, enable the database server
daemon and start it.

NOTE
The installation script w ill not create a database file structure in /USA_DB if this directoryalready exists, w hether it is a local database or a remote database mounted on the file system.

121

Chapter 2: Harmony Server

Running the Database Server on Log- In on GNU/LinuxThe traditional w ay of running the Harmony database server is by installing it as a daemon. This makes the
database server launch immediately on boot, as user usabatch.
Using Service Launcher, it is possible to configure your database server to only launch its database server
service as the logged-in user. This means the database w ill only be accessible if the user configured to run it issigned in. Although this may seem impractical, it may be preferable for security reasons, mainly that thelogged-in user does not need to have administrator privileges to run services through Service Launcher.
If you have enabled the database server daemon, you w ill need to disable and stop it before you can configure
it to launch w ith Service Launcher, to avoid launching tw o instances of the database server.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the database server daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_dbserver stop$ sudo chkconfig toonboom_dbserver off
The database server daemon w ill stop and w ill no longer launch on boot.

How to configure the database server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

2. Do one of the follow ing:l

If Service Launcher is not running, in the GNOME top menu, select Applications > Harmony
22 [Edition] >Service Launcher.

122

Harmony 22 Installation Guidel

If Service Launcher is already running, click on its iconin the system tray.

The Service Launcher application starts.
3. Select the Database Server tab.
4. Click on Launch to verify that the database server launches successfully through Service Launcher.
5. Check the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.
From now on, the database server w ill launch through Service Launcher w hen you log in.

123Chapter 2: Harmony Server

Expanding the File Descriptor Limit for a Database Server on
GNU/Linux
If your database server is likely to have a lot of connected clients, you should expand the file descriptor limit
for the user w ho w ill run the database server daemon.

How to expand the file descriptor limit for the database server
1. In a terminal, open the limits configuration file in a text editor:$ sudo vi /etc/security/limits.conf
2. At the end of the file, just before the # End of file line, add the follow ing lines, replacing<username> w ith the name of the user w ho runs the database server daemon:<username> soft nofile 16384<username> soft nofile 16384

For example, if you installed the database server as a daemon, it w ill run as user usabatch by
default. Hence you w ould need to add the follow ing lines before # End of file:usabatch soft nofile 16384
usabatch soft nofile 16384

3. Save and quit.

124

Harmony 22 Installation Guide

Opening the Firewall Ports for a Harmony Database Server on
GNU/Linux
The GNU/Linux firew all w ill block attempts from other computers to communicate w ith the database server. In
order to circumvent this, the ports used by the database server must be opened.

How to allow connections to the database server to go through the firewall on
CentOS 6, RedHat Entreprise Linux 6 or other systems using the iptables service
1. Add the ports used by the database server to the list of open ports w ith the follow ing commands:$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
5678 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
5680 -j ACCEPT$ sudo service iptables save$ sudo service iptables restart
The GNU/Linux firew all should now allow other machines to connect to the database server.

NOTE
Ports 5678 and 5680 are the default ports used by the Harmony Database server. You cancustomize w hich ports the Database server uses by editing the /USA_DB/Dbserver.conf
configuration file.

How to allow connections to the database server to go through the firewall on
CentOS 7, RedHat Entreprise Linux 7 or other systems using the firewalld service
1. Add the ports used by the database server to the list of open ports w ith the follow ing commands:$ sudo firewall-cmd --permanent --zone=public --add-port=5678/tcp$ sudo firewall-cmd --permanent --zone=public --add-port=5680/tcp$ sudo firewall-cmd --reload
The GNU/Linux firew all should now allow other machines to connect to the database server.

NOTE
Ports 5678 and 5680 are the default ports used by the Harmony Database server. You cancustomize w hich ports the Database server uses by editing the /USA_DB/Dbserver.conf
configuration file.

125

Chapter 2: Harmony Server

Sharing the Harmony Database Files Using NFS on GNU/Linux
Once you have a database file structure and the Harmony database server daemon, you can access the
database from the machine on w hich it w as created. To allow other client machines on your netw ork to accessthe database, you must share its folders using NFS.
If the GNU/Linux firew all is enabled, you must add rules to allow remote connections to the NFS server so as
to allow other machines to connect to the NFS shares.

NOTE
This procedure w ill only allow GNU/Linux and macOS based clients to access the database. If you
w ant W indow s clients to be able to connect to your Harmony server, see About Supporting
W indow s Clients for macOS Servers on page 87.

How to configure the NFS daemon to share your database folders over the network
1. Make sure the NFS service and its utilities are installed:$ sudo yum install nfs-utils
2. Enable and start the rpcbind daemon, the NFS daemon, the NFS lock daemon:$ sudo chkconfig rpcbind on$ sudo service rpcbind start$ sudo chkconfig nfs on$ sudo service nfs start$ sudo chkconfig nfslock on$ sudo service nfslock start
3. Then, open the configuration file /etc/exports in vi to add your database's share directories:$ sudo vi /etc/exports
1. Add the follow ing line to allow clients to access the database files:/USA_DB *(rw,sync)
2. If your database server also has a scene data storage space, add a line w ith a similar syntax toshare it. For example, if the scene data storage space is named /usadata000, add the follow ing
line:/usadata000 *(rw,sync)
3. Save and exit.
4. Run the export command to update the NFS daemon w ith the new configuration:$ sudo exportfs -r
5. Type this command to verify that the new configuration is in effect:126Harmony 22 Installation Guide$ showmount --exports
The utility w ill list all the directories currently shared through NFS.

How to allow connections to the NFS shares to go through the firewall on CentOS 6,
RedHat Entreprise Linux 6 or other systems using the iptables service
1. Open the NFS configuration file in a text editor:$ sudo vi /etc/sysconfig/nfs
2. In the NFS configuration file, remove the hash # sign before the lines w ith the follow ing content, so
as to uncomment them. This w ill make sure the NFS service alw ays uses the same ports, andhence, w ill allow us to safely open those ports in the firew all:l

RQUOTAD_PORT=875

l

LOCKD_TCPPORT=32803

l

LOCKD_UDPPORT=32769

l

MOUNTD_PORT=892

l

STATD_PORT=662

l

STATD_OUTGOING_PORT=2020

3. Add the ports and their protocols to the list of open ports w ith the follow ing commands:$ sudo iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport
2049 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport
111 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m udp -p udp --dport
111 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport
32803 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m udp -p udp --dport
32769 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport892 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m udp -p udp --dport892 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport875 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m udp -p udp --dport875 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -m tcp -p tcp --dport662 -j ACCEPT127

Chapter 2: Harmony Server$ sudo iptables -I INPUT -m state --state NEW -m udp -p udp --dport662 -j ACCEPT$ sudo service iptables save$ sudo service iptables restart
Other machines should now be able to mount the NFS shares.

How to allow connections to the NFS shares to go through the firewall on CentOS 7,
RedHat Entreprise Linux 7 or other systems using the firewalld service
1. In a terminal, enter the follow ing commands:$ firewall-cmd --permanent --add-service=nfs$ firewall-cmd --permanent --add-service=mountd$ firewall-cmd --permanent --add-service=rpc-bind$ firewall-cmd --reload
Other machines should now be able to mount the NFS shares.

128Harmony 22 Installation Guide

About Supporting W indows Clients for GNU/Linux Servers
A GNU/Linux server can natively handle requests from macOS and GNU/Linux clients. How ever, in order toallow W indow s based clients to connect to the server, extra steps must be follow ed:l

The Link Server daemon must be installed. This allow s W indow s clients to create symbolic links onyour macOS server.

lYour database files must be shared via the Samba protocol, w hich is used by W indow s clients to accessthe database.

l

The server.ini file must be filled w ith information on your database server and its scene data storage
spaces. This allow s Configuration W izard to configure W indow s clients automatically.

Installing the Link Server Daemon on GNU/Linux

130

Running the Link Server on Log- In on GNU/Linux

132

Opening the Firewall Ports for the Link Server on GNU/Linux

134

Sharing the Harmony Database Files Using Samba on GNU/Linux

135

Opening the Firewall Ports and Configuring SELinux for a Samba Server on GNU/Linux

138

Configuring a GNU/Linux Database Server for W indows Clients

140

129

Chapter 2: Harmony Server

Installing the Link Server Daemon on GNU/LinuxIf you installed the database server daemon and w ant your GNU/Linux based server to support W indow sclients, you must also install the link server daemon. This daemon runs through the user usabatch, so this user
must be created prior to installing the daemon.

How to create the usabatch user on GNU/Linux
1. In a terminal, enter the follow ing command:$ sudo useradd -m usabatch$ sudo passwd usabatch
2. W hen prompted, enter the passw ord you w ant to assign to the user usabatch, then confirm it.
The user usabatch is now created and can be used to run Harmony daemons.

How to enable the link server daemon on GNU/Linux
1. In a terminal, enter the follow ing command to enable the link server daemon:$ sudo chkconfig toonboom_link_srv on
If the command returns nothing, it succeeded. The link server w ill launch next time you boot themachine.
2. To launch the link server daemon immediately, run the follow ing command:$ sudo service toonboom_link_srv start
The command w ill report w hether it succeeded or failed.

How to enable the link server daemon using the Harmony installation script
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package

130Harmony 22 Installation Guide

4. Run the installer w ith the -d parameter:$ sudo ./install -l
5. W hen prompted, confirm that you w ant to proceed w ith the installation.
The installation script w ill enable and start the link server daemon.

131Chapter 2: Harmony Server

Running the Link Server on Log- In on GNU/LinuxIf you configured your database server to launch using Service Launcher, you w ill also w ant the Link Server tolaunch using Service Launcher, so that it launches in the same circumstances and environment. For more
information on running the database server w ith Service Launcher, see Running the Database Server on LogIn on GNU/Linux on page 122.
If you have already enabled he link server daemon, you w ill need to disable the daemon first to avoid
launching tw o instances of the link server.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the link server daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_link_srv stop$ sudo chkconfig toonboom_link_srv off
The link server daemon w ill stop and w ill no longer launch on boot.

How to configure the link server to launch on log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

2. Do one of the follow ing:l

If Service Launcher is not running, in the GNOME top menu, select Applications > Harmony
22 [Edition] >lService Launcher.

If Service Launcher is already running, click on its icon

The Service Launcher application starts.

132

in the system tray.

Harmony 22 Installation Guide

3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the Link tab.
5. Click on Launch to verify that the Link Server launches successfully through Service Launcher.
6. Check the Launch when Service Launcher starts option.
7. In the top menu, select Server > Save All Settings.
From now on, the link server w ill launch through Service Launcher w hen you log in.

133

Chapter 2: Harmony Server

Opening the Firewall Ports for the Link Server on GNU/LinuxThe GNU/Linux firew all w ill block attempts from other computers to communicate w ith the database server. In
order to circumvent this, the ports used by the database server must be opened.

How to allow connections to the Samba shares to go through the firewall on CentOS
6, RedHat Entreprise Linux 6 or other systems using the iptables service
1. Add the port used by the link server to the list of open ports w ith the follow ing command:$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
5679 -j ACCEPT$ sudo service iptables save$ sudo service iptables restart
The GNU/Linux firew all should now allow other machines to connect to the database server.

NOTE
Port 5679 is the default port used by the Harmony Link server. You can customize w hich port
the Link server uses by editing the /USA_DB/Link_srv.conf configuration file.

How to allow connections to the Samba shares to go through the firewall on CentOS
7, RedHat Entreprise Linux 7 or other systems using the firewalld service
1. Add the port used by the link server to the list of open ports w ith the follow ing command:$ sudo firewall-cmd --permanent --zone=public --add-port=5679/tcp$ sudo firewall-cmd --reload
The GNU/Linux firew all should now allow other machines to connect to the database server.

NOTE
Port 5679 is the default port used by the Harmony Link server. You can customize w hich port
the Link server uses by editing the /USA_DB/Link_srv.conf configuration file.

134

Harmony 22 Installation Guide

Sharing the Harmony Database Files Using Samba on GNU/Linux
In order to allow W indow s clients to access the database's directories remotely, they must be shared by theserver using the Samba protocol.

NOTE
The follow ing commands require elevated privileges. To execute them successfully, you must
either be logged in as a user w ith root privileges, or precede each command w ith sudo.

How to install and configure Samba to share your database folders over the network
1. In a terminal, type the follow ing command to install Samba:$ sudo yum install samba
If samba is not installed, you w ill be prompted to confirm the installation. Confirm and w ait for the
installation to finish. If it is already installed, yum w ill advise you of this and quit.
2. Open the Samba configuration file to configure Samba and add your database directories as Sambashares:$ sudo vi /etc/samba/smb.conf
3. Add the follow ing block to the file to set the global options for the Samba server:[global]encrypt passwords = yes
blocking locks = nooplocks = nolevel2 oplocks = nofollow symlinks = yes
unix extensions = nowide links = yes

4. Add the follow ing to make your Harmony configuration files and binaries accessible to the client:[usa]
comment = Harmony Binaries and Configuration
browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /usr/local/ToonBoomAnimation/harmony[Edition]_22

5. If your server has a scene data folder, add a similar netw ork share configuration to make themaccessible to the client as w ell, w here <scene data folder name> is the name of that folder,135

Chapter 2: Harmony Server

and ### is the number of that folder.
[<scene data folder name>]comment = Harmony Scene Data ###browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /<scene data folder name>For example, if you have a scene data folder named usadata000, you w ould need to add thefollow ing:
[usadata000]
comment = Harmony Scene Data 000
browseable = yesread only = noguest ok = nocreate mask = 0777
directory mask = 0777
path = /usadata000

6. Save and quit.
7. Verify that Samba understands the parameters in its configuration file w ith the follow ing
command:$ testparm
8. A local user must be added to the list of users w ith access to the Samba shares. To do this, type in
the follow ing command, w here <username> is replaced by the name of a user that has access tothis computer:$ sudo smbpasswd -a <username>For example, to give access to user usabatch, type in the follow ing command:$ sudo smbpasswd -a usabatch
You w ill be prompted to assign a passw ord to this new user, then to confirm it. This username andpassw ord w ill be used to connect to the Samba shares.

136Harmony 22 Installation Guide

NOTES
l

The user you are adding to the list of Samba users must already exist as a regular
GNU/Linux user account that has access to this comptuer.

l

On W indow s clients, w hen using the Configuration W izard to configure Harmony
database clients, you must enter this user's username and passw ord in order to beable to connect to the database shares.

9. Enable and start the Samba daemon:$ sudo chkconfig smb on$ sudo service smb start
At this point, your Samba server should be fully operational and your netw ork shares should beaccessible from other computers on your local netw ork.

How to test that the Samba configuration is working
1. You can test that access to your server using Samba is w orking by trying to get a list of yourserver’s Samba shares from another computer, using the method for that computer’s operating
system:l

On macOS: By opening Finder, then selecting Go > Connect to Server in the top menu, andtyping smb://<server name> in the address field.

l

On W indows: By typing opening an Explorer w indow and typing \\<server name> in theaddress bar.

In both cases, <server name> is the hostname of your server.
2. W hen prompted for a username and passw ord, type in the username and passw ord you enteredw hen you created a Samba user in the previous steps.
If you have sucessfully authenticated, you should then see a list of all the Samba shares you
configured (i.e.: usa, USA_DB, usadata000, etc.).
3. Try to select one of the available netw ork shares, and see if you can access it.

137

Chapter 2: Harmony Server

Opening the Firewall Ports and Configuring SELinux for a Samba
Server on GNU/LinuxBy default, client machine w ill not be able to connect to a Samba server running on GNU/Linux, for tw oreasons:l

The GNU/Linux firew all w ill block incoming connections to the Samba server by default.

l

SELinux w ill block client access to the Samba shares by default.

To w ork around this, you must configure the GNU/Linux firew all to accept incoming connections through theports commonly used by Samba. You must also configure SELinux to allow client machines to access the
Samba shares.

How to allow connections to the Samba shares to go through the firewall on CentOS
6, RedHat Entreprise Linux 6 or other systems using the iptables service
1. Add the ports used by the Samba service to the list of open ports w ith the follow ing commands:$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
137 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
138 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
139 -j ACCEPT$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
445 -j ACCEPT$ sudo service iptables save$ sudo service iptables restart
The GNU/Linux firew all should now allow other machines to connect to the NFS shares.

How to allow connections to the Samba shares to go through the firewall on CentOS
7, RedHat Entreprise Linux 7 or other systems using the iptables service
1. Add the Samba service to the list of allow ed services w ith the follow ing commands:$ sudo firewall-cmd --permanent --zone=public --add-service=samba$ sudo firewall-cmd --reload
The GNU/Linux firew all should now allow other machines to connect to the NFS shares.

138Harmony 22 Installation Guide

How to allow connections to the Samba shares to go through SELinux
1. Allow connections to Samba to go through SELinux by entering the follow ing command:$ sudo setsebool -P samba_export_all_ro=1 samba_export_all_rw=1
2. Allow connections to each of your shared folders to go through SELinux by entering the follow ing
command for each share:$ sudo chcon -t samba_share_t <path to share>
For example, if you are configuring a database server w ith the database file structure, the Harmony
binaries and configuration files and one scene data storage space labeled usadata000, you w ould
have to run the follow ing command to allow access to each share:$ sudo chcon -t samba_share_t /usr/local/ToonBoomAnimation/harmony[Edition]_22$ sudo chcon -t samba_share_t /USA_DB$ sudo chcon -t samba_share_t /usadata000
3. Now , refresh the security context of each of your shared folders by entering the follow ing
command for each share:$ sudo restorecon -R <path to share>
For example:$ sudo restorecon -R /usr/local/ToonBoomAnimation/harmony[Edition]_22$ sudo restorecon -R /USA_DB$ sudo restorecon -R /usadata000
At this point, SELinux should allow other machines to connect to your Samba shares w ithout issue.

139Chapter 2: Harmony Server

Configuring a GNU/Linux Database Server for W indows Clients
In order to allow W indow s clients to connect to your server using the Configuration W izard, you must fill inthe server.ini configuration file, w hich is located in the etc subfolder of the Harmony installation package. This
file w ill provide Configuration W izard w ith information on the server as w ell as of each scene data server it isconnected to.

How to configure the server.ini file on GNU/Linux
1. In a terminal, type in the follow ing command:$ sudo vi /usr/local/ToonBoomAnimation/harmony[Edition]_
22/etc/server.ini
2. In server.ini, type in the information for the database server as w ell as the directory name andhostname of every scene data server in your netw ork, like in the follow ing example:[WizardConfig]
ServerName=<server name>InstallationDrive=C
UsaShare=<harmony share name>
UsadbDrive=C
UsadbShare=<database share name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<server name>: The host name of the Harmony database server.

l<harmony share name>: The name of the share that gives access to the Harmony binaries
and configuration files. By default, this share is named usa.

l<database share name>: The name of the share that gives access to the database files.
By default, this share is named USA_DB.

For example, if your database server is called harmonyserver, your Harmony installation is sharedunder the share name usa and your Harmony database is shared under the share name USA_DB,
this w ould be the proper configuration for this server:[WizardConfig]
ServerName=harmonyserver
InstallationDrive=C
UsaShare=usa
UsadbDrive=C
UsadbShare=USA_DB

140

Harmony 22 Installation Guide

3. Under the line starting w ith UsadbShare, enter information about each scene data storage spaceused by your Harmony database, in the follow ing format:
FileSystem<file system number>=C <share name> <server name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<file system number>: The zero-based index of the scene data storage space. For
example, the first scene data storage space for your database should be named
FileSystem0 and the second one, FileSystem1.

l<share name>: The name of the share containing the scene data. Usually, this share iseither named USADATA or usadata, and its name may be follow ed by a zero-padded, zerobased number indicating the index of the scene data storage space. For example, the firstscene data storage space could be named USADATA, usadata000, usadata001, etc.

l<server name>: The host name of the scene data server. If the scene data storage space ishosted on the same machine as the database, then this host name is the same as the hostname for the database. Otherw ise, you must specify the name of the machine on w hich thescene data storage space is located.

For example, if this is the first scene data storage space for your database, it is hosted on acomputer named dataserver and its name is usadata000, the appropriate configuration for thisw ould be as follow s:
FileSystem0=C usadata000 dataserver

IMPORTANTThe variable names and share names in server.ini are case sensitive.

NOTE
server.ini also specifies the drive letter on w hich the softw are, the database files andscene data files are stored. Since w e are configuring a UNIX-based server, there is no actual
drive letter involved. Hence, w e are using the drive letter C as a placeholder so as to respect
the expected format of the server.ini configuration file, but the value of these parameters
is not relevant and w ill not affect your configuration.

141

Chapter 2: Harmony Server

Creating a Scene Data Storage Server on GNU/LinuxYou can create additional scene data storage spaces for your Harmony database on machines. The databaseserver w ill connect to these machines to transmit scene data to the clients, allow ing you to expand the storage
capacity of your database.
Creating a scene data storage space for your Harmony database requires follow ing these steps:
1. Creating a folder named usadata follow ed by the index number of the storage space at the root of themachine.
2. Sharing the folder via NFS and, if W indow s clients must be supported, via Samba as w ell.
3. Mounting this folder on the database server.
4. If W indow s clients must be supported, adding this storage server to the server.ini configuration file.

How to create a scene data storage space
1. In a terminal, enter the follow ing command, w here ### is the padded, zero-based index of thestorage space you are creating, replace ### w ith 001:
$ sudo mkdir -m 777 /usadata###
A folder in w hich scene data w ill be stored is created at the root of the filesystem.

How to share the scene data storage space
1. Sharing a scene data storage space is done the exact same w ay as sharing the server's databasefile system.
l

To share the scene data storage space for macOS and GNU/Linux based clients, see Sharing
the Harmony Database Files Using NFS on GNU/Linux on page 126.

l

To share the scene data storage space for W indow s clients, see Sharing the Harmony
Database Files Using Samba on GNU/Linux on page 135

Once this is done, you should already be able to mount the new scene data storage space on the
database server as w ell as on clients.

142

Harmony 22 Installation Guide

How to mount the new scene data storage space on a GNU/Linux database server
1. In a terminal, create a folder at the root of the filesystem in w hich the new scene data storage
space w ill be mounted w ith the follow ing command, w here <foldername> is the name of thescene data directory you created on the scene data server:$ sudo mkdir -m 777 /<foldername>
2. open the filesystem table in a text editor by typing the follow ing command:$ sudo vi /etc/fstab
3. In the filesystem table, add the follow ing line, replacing <servername> w ith the name of thescene data server and <foldername> w ith the name of the scene data directory you created on
this scene data server:<servername>:/<foldername>/mnt/<foldername>nfs

nfs rw,soft,intr,bg 0 0

4. Save and quit.
5. Attempt to mount the entries of the filesystem table:$ sudo mount -a
6. To make sure that it w orked, try creating a file in the new scene data storage, and verify that it'svisible from both machines. To do this:l

On one machine, enter the follow ing command:$ touch /<foldername>/testfilel

On the other machine, enter the follow ing command to verify that testfile is present$ ls /<foldername>/

How to add the scene data storage file to the server.ini configuration file
1. In a terminal, type in the follow ing command:$ sudo vi /usr/local/ToonBoomAnimation/harmony[Edition]_
22/etc/server.ini
If the file w as already configured, it most likely contains configuration in the follow ing format:[WizardConfig]
ServerName=<name of Harmony server>
InstallationDrive=C
UsaShare=usa
UsadbDrive=C

143

Chapter 2: Harmony Server

UsadbShare=USA_DB
FileSystem0=C usadata000 <name of first scene data server>

2. Under the last line starting w ith FileSystem0 w hich contains information about an existing scene
data storage space, enter the information about your new scene data storage space in thefollow ing format:
FileSystem<file system number>=C <share name> <server name>

Replace the tags betw een <> brackets w ith the appropriate values. Make sure to remove the <>brackets from the configuration file as w ell:l<file system number>: The zero-based index of the scene data storage space. For
example, the first scene data storage space for your database should be named
FileSystem0 and the second one, FileSystem1.

l<share name>: The name of the share containing the scene data. Usually, this share iseither named USADATA or usadata, and its name may be follow ed by a zero-padded, zerobased number indicating the index of the scene data storage space. For example, the firstscene data storage space could be named USADATA, usadata000, usadata001, etc.

l<server name>: The host name of the scene data server. If the scene data storage space ishosted on the same machine as the database, then this host name is the same as the hostname for the database. Otherw ise, you must specify the name of the machine on w hich thescene data storage space is located.

For example, if this is your second scene data storage space for your database server, it is hosted
on a computer named newdataserver and is named usadata001, its configuration w ould be as
follow s:
FileSystem1=C usadata001 newdataserver

IMPORTANTThe variable names and share names in server.ini are case sensitive.

144

Harmony 22 Installation Guide

NOTE
The first information for a scene data storage space, C, is actually the drive letter on w hich thescene data storage space is located. Since GNU/Linux does not use drive letters, there is no
drive letter for this storage space, and w e are only specifying a drive letter to respect theformat of the server.ini configuration file. This value does not have an effect your server
configuration.

145

Chapter 2: Harmony Server

Setting Up Static IPs for W ebCC on GNU/LinuxIt is common to configure server machines to have a static IP. This avoids having to rely on DNS resolution tofind the server w hen its IP address changes, and it also allow s you to associate the hostname to the server's
static IP address on the machine to skip DNS resolution altogether, increasing netw ork performance.
If your machine is currently connected to a DHCP server that dynamically assigns IP addresses, you canconfigure your machine to permanently use its current IP address. To do this, you can start by making note of
the information for your current netw ork connection, then using these parameters for a permanent IP address.

How to obtain your current network configuration on CentOS 6
1. To obtain your machine's hostname, enter the follow ing command:$ hostname
W rite dow n the output value.
2. To obtain the netw ork domain, enter the follow ing command:$ hostname -d
W rite dow n the output value.
3. To obtain your machine's default gatew ay and netw ork device, enter the follow ing command:$ routeThe output w ill look like this:Destination
10.120.0.0
default

Gateway*<default gateway>

Genmask<subnet mask>
0.0.0.0

Flags Metric Ref
U
1
0
UG
0
0

Use Iface
0 <device name>0 <device name>One of the row s w ill have default in the destination column. In this row , the name of the device in
the Iface column is the name of your default netw ork device. W rite dow n the name of that device.
4. To obtain your machine's IP and subnet mask, enter the follow ing command, replacing <device
name> w ith the name of the device noted in the previous step:$ nmcli -f all dev list iface <device name>
Information about the netw ork interface w ill appear, in either one of the follow ing formats:
GENERAL.DEVICE:
GENERAL.TYPE:
GENERAL.DRIVER:
GENERAL.HWADDR:
GENERAL.STATE:CAPABILITIES.CARRIER-DETECT:CAPABILITIES.SPEED:<device name>802-3-ethernet
tg3<MAC address>
connected
yes1000 Mb/s146

Harmony 22 Installation Guide

WIRED-PROPERTIES.CARRIER:
IP4-SETTINGS.ADDRESS:
IP4-SETTINGS.PREFIX:
IP4-SETTINGS.GATEWAY:
IP4-DNS1.DNS:on<IPv4 address><prefix> (<subnet mask>)<default gateway><DNS server address>

W rite dow n the IPv4 address, the subnet mask, the default gatew ay as w ell as every DNS server
address listed.

NOTE
You can also obtain the IP address (inet addr) and netw ork mask (Mask) of your device w ith
the command:$ ifconfig <device name>How to obtain your current network configuration on CentOS 7
1. To obtain your machine's hostname, enter the follow ing command:$ hostname
W rite dow n the output value.
2. To obtain the netw ork domain, enter the follow ing command:$ hostname -d
W rite dow n the output value.
3. To obtain your machine's default gatew ay and netw ork device, enter the follow ing command:$ routeThe output w ill look like this:Destination
10.120.0.0
default

Gateway*<default gateway>

Genmask<subnet mask>
0.0.0.0

Flags Metric Ref
U
1
0
UG
0
0

Use Iface
0 <device name>0 <device name>One of the row s w ill have default in the destination column. In this row , the name of the device in
the Iface column is the name of your default netw ork device. W rite dow n the name of that device.
4. To obtain your machine's IP and subnet mask, enter the follow ing command, replacing <device
name> w ith the name of the device noted in the previous step:$ nmcli -p -f IP4 connection show <device name>
Information about the netw ork interface w ill appear. The output w ill be in this format.

147

Chapter 2: Harmony Server===============================================================================
Activate connection details (0568a4c4-092a-46e9-9f25-2295a1389d6e)===============================================================================
IP4.ADDRESS[1]:<IPv4 address>/<prefix>
IP4.GATEWAY:<default gateway>
IP4.DNS[1]:<DNS server address>
IP4.DOMAIN[1]:<search domains>

W rite dow n the IPv4 address, the default gatew ay address, the DNS server address(es) and thesearch domain(s).
To obtain your subnet mask, enter the follow ing command, replacing <device name> w ith thename of the device noted in the previous step:$ nmcli -p -f DHCP4 connection show <device name> | grep 'subnet_mask'
The output should look like this:subnet_mask = <subnet mask>

DHCP4.OPTION[3]:W rite dow n the subnet mask.

NOTE
You can also obtain the IP address (inet) and netw ork mask (netmask) of your device w ith
the command:$ ifconfig <device name>How to set up a static IP for CentOS 6 and 7
1. Before you do this, make sure you have the follow ing information for your machine:lName of default netw ork device (ie: eth0, p3p1)lHostnamelDomain namelSearch domain(s)lIPv4 addresslNetw ork mask

148

Harmony 22 Installation Guidel

Default gatew ay addressl

DNS server address(es)2. Open your machine's netw ork configuration file for editing:$ sudo vi /etc/sysconfig/network
3. Configure the file as follow s, replacing the bolded text w ith the appropriate values:
NETWORKING=yes
HOSTNAME=<hostname>.<domain name>

4. Open your default netw ork interface's configuration file for editing. This file w ill be named ifcgfollow ed by the name of the netw ork interface you noted earlier. For example, if your netw ork
interface is named eth0, the configuration file w ill be named ifcfg-eth0:$ sudo vi /etc/sysconfig/network-scripts/ifcfg-<device name>
5. Configure the file w ith the appropriate values for the follow ing parameters. If a value is alreadydeclared for one of these parameters, replace it. If not, add it to the file:
DEVICE="<device name>"
BOOTPROTO=static
IPADDR=<IPv4 address>
NETMASK=<network mask>
GATEWAY=<default gateway>
ONBOOT=yes

6. Open the DNS configuration file for editing:$ sudo vi /etc/resolv.conf
7. Configure the file as follow s, replacing the bolded text w ith the appropriate values:
search <search domain mames>
nameserver <DNS server address>

NOTES
l

If you have several search domains, enter them all on the same line after search,separated by spaces.

l

If you have several DNS servers, add one nameserver line for each address.

8. Restart the netw ork service:$ sudo service network restart149

Chapter 2: Harmony Server

Checking the Database Server Log on GNU/Linux
In order to troubleshoot problems w ith the Harmony database server, you can look through its log. This isdone differently depending on w hether you installed the database server as a daemon or using Service
Launcher.
If your server is configured for W indow s clients, you can also check the link server log for issues.

How to check the log for the database server daemon
1. In a terminal, enter the follow ing command:$ less /tmp/tbdbserver.log

How to check the log for the link server daemon
1. In a terminal, enter the follow ing command:$ less /tmp/Link_srv.log

How to check the log for the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

How to check the log for the link server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher
The Service Launcher application opens.
3. Select the Link tab.
4. In the bottom half, select the Log tab.

150

icon.

Harmony 22 Installation Guide

5. Click on the View Complete Log button in the bottom-right corner.

151

Chapter 2: Harmony Server

Launching the Database Server Manually in GNU/LinuxYou can start the database server directly from a terminal. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems.
If your server needs to handle W indow s clients, you can also launch the link server in a different terminal toensure that both services w ork.
You can view the output of both services directly in the terminal in w hich you launch them as they start andhandle requests.

How to start the database server manually
1. In a terminal, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/tbdbserver

How to start the link server manually
1. In another terminal, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin/Link_
srv

152

Harmony 22 Installation Guide

Stopping and Restarting the Database Server on GNU/LinuxIf you installed the database server as a daemon, you can stop it and restart it using the service commandline tool. If you installed it using Service Launcher, you can stop it and restart it manually in Service Launcher.
If you have installed the link server so as to be able to handle W indow s clients, stopping and restarting it may
also be necessary for the intended purpose.

How to stop and restart the database server daemon
1. In a terminal, enter the follow ing command:$ sudo service toonboom_dbserver stop
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo service toonboom_dbserver start

TIP
You can also restart the service instantly w ith the follow ing command:$ sudo service toonboom_dbserver restart

How to stop and restart the link server daemon
1. In a terminal, enter the follow ing command:$ sudo service toonboom_link_srv stop
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo service toonboom_link_srv start

TIP
You can also restart the service instantly w ith the follow ing command:$ sudo service toonboom_link_srv restart

How to stop and restart the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.

153

Chapter 2: Harmony Server

2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

How to stop and restart the link server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Link Server tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

154

Harmony 22 Installation Guide

Pausing and Resuming the Database Server on GNU/LinuxIf you need to perform maintenance or updates on a Harmony server, you can pause it instead of stopping itcompletely.
Users w ho attempt to save a scene w hile the server is paused w ill receive a w arning message. The server w illqueue the save and commit the changes w hen the server is resumed.

How to pause the database server
1. In a command prompt, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin/dbu -p

How to check pause status of the database server
1. In a command prompt, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin/dbu -P

How to resume the database server
1. In a command prompt, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin/dbu res

155Chapter 2: Harmony Server

Uninstalling the Database Server on GNU/LinuxIf you installed the database server as a daemon, you can uninstall it using the chkconfig command line tool.
If you installed it using Service Launcher, you can uninstall it in Service Launcher.

How to disable the database server daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_dbserver stop$ sudo chkconfig toonboom_dbserver off
The database server daemon w ill stop and w ill no longer launch on boot.

How to disable the link server daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_link_srv stop$ sudo chkconfig toonboom_link_srv off
The link server daemon w ill stop and w ill no longer launch on boot.

How to uninstall the database server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Database Server tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

How to uninstall the link server in Service Launcher
1. Make sure you are currently signed in as the user running the service.

156

Harmony 22 Installation Guide

2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the Link Server tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

157

Chapter 2: Harmony Server

Connecting Client W orkstations to a Harmony Database Server
On a Harmony database server, database files and scene data files are present and sorted using a specific filestructure. To connect a w orkstation to a Harmony database server, the structure of the database file system
must be simulated on the client machine using file sharing.
A client w orkstation configuration is permanent, meaning that it is only necessary to configure a client toconnect to a specific Harmony database server once. Once a client w orkstation is properly configured, you cansimply launch Harmony or any other Harmony application at any time and connect to the server using yourHarmony database account.

158

Harmony 22 Installation Guide

Configuring Harmony Server Clients on W indows
Provided that your server is properly configured, a W indow s machine can be configured to connect to a
Harmony database server using Configuration W izard. The w izard creates W indow s shortcut (.lnk) files
pointing to the different netw ork shares used for the database on the hard drive of the client machine, andconfigures a script that signs in to those netw ork shares on boot.
Those W indow s shortcuts have the same name as the share they connect to and are placed at the root of yourstorage drive, and Harmony interprets those shortcuts as if they w ere directories, a lot like the w ay symbolic
links w ork on UNIX systems.
Connecting a W indows Client to a Database Server Using Configuration W izard

160

Manually Configuring a W indows Client to Connect to a Harmony Database

161

Configuring the Hosts File for a W indows Client

164

About Connecting to a Harmony Database W ithout Using Shortcut Files on W indows

165

Configuring the Shortcuts File on W indow s

166

Setting a Custom Location for the Shortcuts Configuration File on W indow s

168

Troubleshooting Client Connections on W indows

170

159

Chapter 2: Harmony Server

Connecting a W indows Client to a Database Server Using
Configuration W izard
Provided that your server is properly configured, you can quickly configure a W indow s w orkstation to connect
to the Harmony server as a client using the Configuration W izard. You must perform this task for every
w orkstation that w ill need to connect to your database server.

How to set up a Harmony database client on W indows
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
1. In the Toon Boom Harmony Configuration dialog, select the ... button right of Database.
2. In the Toon Boom Harmony Database Creation dialog, select Client and click on Next.
3. Under W hat is the name of the server?, type in the hostname of the database server.
4. Under W hat is the User?, type in the name of an user account that has access to the databaseshare.
5. Under W hat is the Password?, type in the passw ord for the selected user account.
6. Click on Next.
7. In the Database changes field, verify that all the intended changes are correct, then click on Finish.
You should now be able to launch Harmony, Control Center, Paint, Scan and Play and connect tothe Harmony Server database through these applications.

160Harmony 22 Installation Guide

Manually Configuring a W indows Client to Connect to a Harmony
Database
On W indow s, the Configuration W izard uses the server.ini file located on the Harmony server to automaticallyconfigure clients to connect to each netw ork share used by the database. You can also make this configuration
manually. This can be useful if you simply need to add a new scene data storage space to a client, if you madechanges to your server configuration or if you need to use different username and passw ord combinations fordifferent netw ork share used by your database, as the Configuration W izard w ill use the same credentials forall of them.
Configuring a W indow s client is done in tw o steps:l

Adding the path, username and passw ord to connect to each share used by the Harmony database in
the Connections tab of the Harmony Control Panel. Typically, there should be one share named USA_DB, w hich contains the database file structure, and one share named usadata follow ed by a zerobased padded number for each scene data server, such as usadata000, usadata001, etc.

lCreating a shortcut that points to each of these shares at the root of the main storage drive of yourmachine.

On W indow s, the path to a netw ork share is w ritten as follow s:\\servername\sharename
This is how the path to each database share must be w ritten in both the Harmony Control Panel and theshortcut files.

How to add Harmony network share connections using the Harmony Control Panel
1. In the Start menu, open the Programs list, then select Harmony 22 [Edition] > Tools >Control

Panel.
2. Confirm that you w ant to make changes to your device.
The Toon Boom Harmony Control Panel appears.
3. Open the Connections tab.
4. In the Sharename field, enter the full UNC path of the netw ork share you w ant to add. For
example, if you are creating a connection for USA_DB and this netw ork share is located on amachine named harmony server, you w ould type \\harmonyserver\USA_DB.
5. In the Username field, enter the username of a user w ho has access to this netw ork share. Bydefault, database files created by the Configuration W izard can be accessed w ith the user
usabatch.
6. In the Password field, enter the passw ord of the user account specified in the Username field.
7. Click on Connect to verify that the connection can be made using these parameters.

161

Chapter 2: Harmony Server

8. Click on Create Connection to permanently add this connection to the list of connections that are
made on boot.
9. Repeat for each scene data storage space used by the database. For example, if your database hasa single scene data storage space named usadata000 and it is located on the same server as the
database files (harmonyserver), you w ould need to add the share\\harmonyserver\usadata000 using the same credentials.
10. Also repeat for the usa share, w hich is typically located on the same machine as the USA_DB share.

How to add shortcuts to the Harmony network shares to your storage drive
1. Go to your desktop by minimizing all application w indow s.

NOTE
Although the shortcuts must be placed in the root of your storage drive, W indow s
Explorer w ill not allow creating shortcuts directly in this location. Therefore, thefollow ing steps explain how to create the shortcuts on your desktop, then move themto the root of your storage drive.

2. Right-click anyw here on the desktop, and select New > Shortcut.
The Create Shortcut dialog appears.
3. Under Type the location of the item:, type the full UNC path of the netw ork share you w ant toadd. For example, if you are creating a shortcut pointing to USA_DB and this netw ork share islocated on a machine named harmony server, you w ould type \\harmonyserver\USA_DB.
4. Click on Next.
5. Under Type a name for this shortcut:, type in the name of the share and nothing else. For example,
if you are creating a shotcut pointing to \\harmonyserver\USA_DB, type in USA_DB.
6. Click on Finish.
A new shortcut file is created on your desktop.
7. Open an Explorer w indow .
8. Navigate to the root of the main storage drive for your w orkstation. Typically, this storage drive isnamed C:
9. Drag and drop the shortcut you just created to the root of your storage drive.
10. W hen prompted, confirm that you w ant to provide administrator permission to move the shortcut.

162Harmony 22 Installation Guide

11. Repeat for each scene data storage space used by the database. For example, if your database hasa single scene data storage space named usadata000 and it is located on the same server as the
database files (harmonyserver), you w ould need to add another shortcut pointing to\\harmonyserver\usadata000 w ith the name usadata000.

163

Chapter 2: Harmony Server

Configuring the Hosts File for a W indows Client
W hen a client connects to a server using its hostname, it must first go through the netw ork in order to obtain
the IP address associated w ith that hostname, w hich adds overhead to the connection.
A hosts file is a configuration file w hich allow s you to forcefully associate certain hostnames w ith specific IP
addresses. This can allow you to set up a client machine to directly connect to the IP address of your Harmony
database server w ithout having to query the netw ork for its address first, w hich may increase netw ork
performance. How ever, this should only be done if your database server has a static IP address w hich you do
not intend to change. If the IP address of your server changes, the information in the host file w ill no longer be
accurate and you w ill be unable to connect to the server unless you update or remove the configuration in thehosts file.

How to associate the Harmony database server hostname to its IP address
1. In the Start menu, open the Programs list, then select W indow s Accessories.
2. Right-click on Notepad and select More > Run as administrator.
3. In the Notepad top menu, select File > Open.
4. In the file type drop-dow n near the bottom-right corner of the Open dialog, select All Files (*.*)
5. Navigate to C:\Windows\System32\drivers\etc and open the file named hosts.
6. At the bottom of the file, add a new line.
7. Type in the permanent IP address of the Harmony database server follow ed by its hostname,separated by a space. For example, if your database server is named harmonyserver and its IP
address is 10.127.1.1, you w ould type in the follow ing:
10.127.1.1 harmonyserver
8. If your Harmony database server uses other machines for scene data storage, repeat for eachmachine used for the server so as to associate each machine's hostname to their permanent IP
address.
9. In the top menu, select File > Save.
10. Reboot the machine.

164Harmony 22 Installation Guide

About Connecting to a Harmony Database W ithout Using Shortcut
Files on W indows
By default, w hen connecting a client w orkstation to a Harmony server, shortcut files are placed at the root of
the main storage drive (typically C:) pointing to the location of each netw ork share used by the Harmony
database.
How ever, it is also possible to configure the location of these netw ork shares in the shortcuts.conf
configuration file instead of using shortcuts. This lightens the process of accessing database files by removing
the overhead from reading the shortcut files.
The shortcuts.conf file must be located in the etc subfolder of the Harmony installation directory bydefault, but it can be located anyw here on your computer provided that you specify the location of this file in
the USA_DB_CONFIG environment variable. This can allow users to change the location of the Harmony
database server they are connecting to w ithout needing administrator privileges.

165

Chapter 2: Harmony Server

Configuring the Shortcuts File on W indows
The shortcuts.conf configuration file should be located in the etc subfolder of the Harmony installation
directory. It does not exist by default, so it must either be created from scratch, or using the sample fileprovided w ith Harmony.

How to create and edit the shortcuts.conf configuration file using the sample
shortcuts.conf file
1. In the Start menu, open the Programs list and select W indow s System.
2. Right-click on Command Prompt and select More > Run as administrator
3. Enter the follow ing command to copy the sample shortcuts.conf file to its intended location:> CD C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]> COPY resources\samples\shortcuts.conf etc\
4. Enter the follow ing command to open the shortcuts.conf file in Notepad as an administrator:> notepad etc\shortcuts.conf

How to fill up the shortcuts.conf configuration file
1. If you used the sample shortcuts.conf file, the file w ill already have explainations on lines startingw ith a #, w hich are ignored by Harmony, follow ed by the header shortcut_list :. If you are creating
the shortcuts.conf file from scratch, make sure to start by typing in the header:shortcut_list :2. Under shortcut_list : add a line specifying the location of the database files (USA_DB) in thefollow ing format, w here <harmony server> is the hostname of the computer on w hich the databasefiles are located:/USA_DB //<server name>/USA_DB

For example, if the database files are located on a machine named harmonyserver, you w ould add
this line:/USA_DB //harmonyserver/USA_DB

166

Harmony 22 Installation Guide

3. For each scene data storage used by the Harmony server, add a line in the same format. For
example, if your Harmony database has a scene storage space named usadata000 on the samemachine (harmonyserver), and another scene data storage space named usadata001 on a machinenamed scenedataserver, you w ould add the follow ing lines:/usadata000 //harmonyserver/usadata000/usadata001 //scenedataserver/usadata001

4. Save.
The next time you launch Harmony, it w ill rely on the configuration in shortcuts.conf instead of
the shortcut files in the root of your storage drive to connect to the database netw ork shares.

167

Chapter 2: Harmony Server

Setting a Custom Location for the Shortcuts Configuration File on
W indows
By default, shortcuts.conf should be located in Harmony's etc subfolder, w hich can only be modified byusers w ith administrator privileges. How ever, it is possible to specify a for shortcuts.conf in the USADB_CONFIG_FILE environment variable.
As a result, a user can place a shortcuts.conf file in their Documents folder and make Harmony read it,
w ithout requiring administrator privileges. Likew ise, an administrator can place the shortcuts.conf file in a
specific location that can be edited by any user, and set the environment variable to point to this file for allusers.

How to set a custom location for the shortcuts.conf file for the current user
1. First, use a text editor (ie: Notepad) to create a shortcuts.conf configuration file in the preferred
location—see Configuring the Shortcuts File on W indow s.
2. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

3. Select User Accounts, then User Accounts again.
4. In the left pane, select Change my environment variables.
5. Under the User variables list, click on New.
The New User Variable dialog appears.
6. In the Variable Name field, type in USADB_CONFIG_FILE.
7. Click on Browse File.
An Open dialog appears.
8. In the Open dialog, navigate to and select the shortcuts.conf file you created in the preferred
location.
9. In the New User Variable dialog, click on OK.
10. In the Environment Variables dialog, click on OK.
The next time you launch Harmony, it w ill use the parameters in the shortcuts.conf file in thecustom location w here you saved it.

168Harmony 22 Installation Guide

How to set a custom location for the shortcuts.conf file for all users
1. First, use a text editor (ie: Notepad) to create a shortcuts.conf configuration file in the preferred
location—see Configuring the Shortcuts File on W indow s.
2. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

3. Select System and Security > System.
4. In the left pane, select Advanced system settings.
5. Open the Advanced tab.
6. Click on Environment Variables.
7. Under the System variables list, click on New.
The New System Variable dialog appears.
8. In the Variable Name field, type in USADB_CONFIG_FILE.
9. Click on Browse File.
An Open dialog appears.
10. In the Open dialog, navigate to and select the shortcuts.conf file you created in the preferred
location.
11. In the New System Variable dialog, click on OK.
12. In the Environment Variables dialog, click on OK.
The next time you launch Harmony, it w ill use the parameters in the shortcuts.conf file in thecustom location w here you saved it.

169Chapter 2: Harmony Server

Troubleshooting Client Connections on W indows
If your client is unable to connect to the database, a good w ay to diagnose the issue is to verify that you are atleast able to connect to and to navigate the database server's shared folders. To test that, you can type the
UNC path of one of the database's shared folders in the address bar of an Explorer w indow . For example, if
the database is hosted on a server named harmonyserver, try to open the follow ing location:\\harmonyserver\USA_DB
Then, you can follow the troubleshooting tips depending on how W indow s handled your attempt to connect
to the share:l

W indow s Accesses the Database Share W ithout Issue on page 170l

W indow s Prompts for a Username and/or Passw ord on page 171l

W indow s is Unable to Access the Share and Displays an Error Message on page 171

W indows Accesses the Database Share W ithout Issue
If you have access to the shared folders, but Harmony is unable to connect to the database, this means theserver is properly configured to share files, but not to act as a Harmony database server, either because:l

The database server service is not running on the server machine. You can check if this is the issue by
running the server service manually in a terminal on the server machine, then attempting to connect
from the client machine again. To do this, depending on the platform of your Harmony server, see:l

W indows: Launching the Database Server Manually on W indow s on page 70lmacOS: Launching the Database Server Manually in macOS on page 110l

GNU/Linux: Launching the Database Server Manually in GNU/Linux on page 152

NOTE
Running the database server service directly from a terminal also allow s you to immediately
see if the service encounters any errors w hen launching.

l

The server machine is refusing connections to the Harmony database server because of its firew all
rules. To resolve this, see:l

W indows: Opening the Firew all Ports for a Harmony Database Server on W indow s on page 57l

GNU/Linux: Opening the Firew all Ports for a Harmony Database Server on GNU/Linux on page
125 and Opening the Firew all Ports for the Link Server on GNU/Linux on page 134.

NOTE
The macOS firew all is not know n to block connections to a Harmony server by default.

170

Harmony 22 Installation Guide

W indows Prompts for a Username and/or Password
If you get prompted for a username or a passw ord, this means that the server is properly configured to shareits files, but Harmony failed to establish a connection to the shared folders w hen you logged in. This may be
because:lHarmony w as not configured to use the right credentials to access the shares.
W hen you use Configuration W izard to configure a client to connect to a database server, you areprompted to type in a username and passw ord to access the database server's shared folders.
Configuration W izard saves those credentials and, w hen you log in to your W indow s account, Harmony
attempts to establish a connection w ith those shared folders using the username and the passw ord you
entered.
You can check if this is the issue by attempting to configure your client again using Configuration
W izard—see Connecting a W indow s Client to a Database Server Using Configuration W izard on page160.

W indows is Unable to Access the Share and Displays an Error Message
If you are getting an error message, this means that your client is either unable to find the shared folder on
your server, or that your server is refusing to let your client access it. This may be because:lThere is something w rong w ith the configuration of one or several of the database shares. Make sure
you configured the shared folders properly on your server:l

W indows: The shares on the actual Harmony database server are configured automatically by
Configuration W izard. For shares on machines other than the Harmony database server, see
Creating a Scene Data Storage Space on W indow s on page 59.

lmacOS: Sharing the Harmony Database Files Using Samba on macOS on page 91 and Creating
a Scene Data Storage Server on macOS on page 100.

l

GNU/Linux: Sharing the Harmony Database Files Using Samba on GNU/Linux on page 135 andCreating a Scene Data Storage Server on GNU/Linux on page 142.

l

If the server is running GNU/Linux, the GNU/Linux firew all and/or SELinux may be blocking incoming
connections to its Samba shares—see Opening the Firew all Ports and Configuring SELinux for a Samba
Server on GNU/Linux on page 138.

l

If your client is using W indow s 10, the problem might be caused by the version of the Samba protocol
the server is using. Servers that use Samba to share files usually use the SMB 2.0, SMB 2.1 or SMB 3.0
protocol. How ever, some Samba servers may still be using the deprecated SMB 1.0 protocol. By
default, W indow s 10 computers are configured to be unable to connect to Samba servers that use the
SMB 1.0 protocol, because SMB 1.0 is considered unsafe.
There are three common cases w here a Samba server w ill use the SMB 1.0 protocol:

171Chapter 2: Harmony Serverl

The server runs CentOS 6.

l

The server runs macOS, and Samba w as installed through third party means, such as brew or
SMBup.

l

The server runs W indow s 10, and has the optional SMB 1.0/CIFS Server component enabled.

The optimal solution to this issue is to configure the server to only use SMB 2.0 and up. This is possible
in the three cases above.
The alternative solution is to configure your W indow s 10 clients to be able to connect to Samba serversthat use SMB 1.0. This should only be done if it is not possible to use SMB 2.0 and up across the
netw ork, as SMB 1.0 is considered unsafe.

How to configure a GNU/Linux CentOS 6 server to use SMB 2.0 and up
1. In a terminal, type in the follow ing command:$ sudo vi /etc/samba/smb.conf
2. Inside the file, scroll dow n to the section that starts w ith [global].
3. Press the i key to enter insert mode.
4. Add the follow ing line to the [global] section:
protocol = SMB2
5. Press Esc, then type :wq and press Enter/Return to save and quit.
6. In the terminal, restart the Samba server w ith the follow ing command:$ sudo service smb restart
From now on, your W indow s 10 client should be able to connect to your GNU/Linux Samba server.

How to configure a macOS server to use SMB 2.0 and up
1. In a terminal, type in the follow ing command:$ sudo vi /opt/local/etc/samba3/smb.conf
2. Inside the file, scroll dow n to the section that starts w ith [global].
3. Press the i key to enter insert mode.
4. Add the follow ing line to the [global] section:
protocol = SMB2
5. Press Esc, then type :wq and press Enter/Return to save and quit.
6. In the terminal, restart the Samba server w ith the follow ing command:172

Harmony 22 Installation Guide$ sudo launchctl unload /Library/LaunchDaemons/org.samba.smbd.plist$ sudo launchctl load /Library/LaunchDaemons/org.samba.smbd.plist
From now on, your W indow s 10 client should be able to connect to your macOS Samba server.

How to configure a W indows 10 server to use SMB 2.0 and up
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, select Programs > Turn W indows features on or off.
3. In the features list, scroll to and expand SMB 1.0/CIFS File Sharing Support.
4. Under SMB 1.0/CIFS File Sharing Support, make sure that the item SMB 1.0/CIFS Server isunchecked.
5. Click OK.
You may be prompted to restart the machine for the changes to take effect. Afterw ards, yourW indow s 10 clients should be able to connect to your W indow s shares.

How to configure a W indows 10 client to connect to SMB 1.0/CIFS servers
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, select Programs > Turn W indows features on or off.
3. In the features list, scroll to and expand SMB 1.0/CIFS File Sharing Support.
4. Under SMB 1.0/CIFS File Sharing Support, make sure that the item SMB 1.0/CIFS Client ischecked.
5. Click OK.
You may be prompted to restart the machine for the changes to take effect. Afterw ards, yourW indow s 10 client should be able to connect to your server's Samba shares.

173

Chapter 2: Harmony Server

Configuring Harmony Server Clients on macOSOn macOS and GNU/Linux, a client w orkstation is configured to connect to a Harmony server by mounting thedifferent netw ork shares used for the database on directories w ith the same name as these shares, at the rootof the filesystem. As a result, all of the database and scene data files become part of your machine's filesystem, and the path to each file in your database is the same path on both the client machine and the servermachine, allow ing seamless access to all of your scene data on any machine. The most straightforw ard
approach to this is to configure these shares to be automatically mounted on boot using the file system table(fstab) file.
Connecting a macOS Client to a Database Server

175

Setting the User File Creation Permission Mask on macOS

183

Configuring the Hosts File for a macOS Client

184

About the Location of Mount Points on macOS

185

Configuring the Shortcuts File on macOS

186

Setting a Custom Location for the Shortcuts Configuration File on macOS

187

174

Harmony 22 Installation Guide

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 tw o follow ing w ays:l

On macOS clients prior to macOS 10.15 (Catalina), you can do it using the traditional method, that is bycreating mount points to the netw ork shares of your database server and your scene data servers in theroot of the file system, like so: /USA_DB, /usadata000, /usadata001, etc.

lmacOS clients w ith 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 theirlocation—see About the Location of Mount Points on macOS on page 185.

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 (/) w as automatically moved to /Users/Shared/RelocatedItems.

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 w ay that is compatible w ith macOS 10.15(Catalina) or later, as it also w orks on previous versions of macOS.
If your netw ork shares use the NFS protocol, you can create mount points for them using macOS‘s autofs
system.
How ever, if your netw ork shares use the Samba protocol, the only know n w orking w ay of mounting them
automatically on log-in is to connect to these shares manually in Finder, creating symbolic links to thoseshares 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 tw o important
limitations:l

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.

l

If several users are configured to mount those netw ork shares, only one of these users at a time can belogged-in. This is because if tw o logged-in users have the same netw ork shares mounted via Finder or
log-in items, the name of the mount points for second user to log-in w ill be different. One macOS, amounted Samba share can only be accessed by the user w ho mounted it. Therefore, on the second
logged-in user’s account, Harmony w ill try to access the first logged-in user’s mount points and w ill bedenied access.

175Chapter 2: Harmony Server

How to automatically mount Harmony datbase network shares using the NFS
protocol on macOS 10.15 (Catalina) or later
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 follow ing line to the file:/- auto_nfs -nobrowse,nosuid

This w ill 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 follow ing format for each netw ork share that your Harmony database requires:/System/Volumes/Data/mnt/<share name> -fstype=nfs,rw,soft,intr,resvport nfs://<server name>:/<For example, if your main database server is named harmonyserver and hosts the database files(USA_DB) as w ell as the first scene data storage space, named usadata000, and you haveanother scene data server called scenedataserver hosting the second scene data storage space,
named usadata001, you w ould need to add the follow ing lines:/System/Volumes/Data/mnt/USA_DB-fstype=nfs,rw,soft,intr,resvport nfs://harmonyserver:/USA/System/Volumes/Data/mnt/usadata000 -fstype=nfs,rw,soft,intr,resvport nfs://harmonyserver:/usa/System/Volumes/Data/mnt/usadata001 -fstype=nfs,rw,soft,intr,resvport nfs://scenedataserver:/u5. The paths starting w ith /mnt/ are the folders w here you w ill mount your netw ork shares on yourw orkstation, referred to as mount points. Those folders must exist on your w orkstation and must
be empty. Hence, you must create them before you can try mounting those netw ork shares. First,
type the follow ing command to create the /mnt directory:$ sudo mkdir /System/Volumes/Data/mnt
6. Then, for each netw ork share you have, type in the follow ing command:$ sudo mkdir -m 777 /System/Volumes/Data/mnt/<share name>
7. W e w ill configure Harmony w ill to look for these shares in /System/Volumes/Data. Thus, youmust create symbolic links pointing to each mount point in /System/Volumes/Data. To do this, typein the follow ing command for each netw ork share:$ sudo ln -s /System/Volumes/Data/mnt/<share name>/System/Volumes/Data/<share name>176Harmony 22 Installation Guide

8. Now , to configure Harmony to look for the mountpoints in /System/Volumes/Data, w e must
edit its shortcuts.conf configuration file. In a terminal, enter the follow ing command:$ sudo vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/shortcuts.conf"
9. At the top of the file, type the follow ing header line:
shortcut_list :10. Under shortcut_list :, add a line specifying the location of the mount point for each of themounted netw ork shares in the follow ing format:/<share name> /<full path to symlink to mount point>

In the example described above, this w ould result in the follow ing:
/USA_DB/System/Volumes/Data/USA_DB/usadata000 /System/Volumes/Data/usadata000/usadata001 /System/Volumes/Data/usadata001

11. Save and quit.
You should now be able to connect to your database server in Harmony. macOS w ill automaticallyattempt to mount the shares you configured as soon as any application tries to access them.

How to automatically mount Harmony datbase network shares using the NFS
protocol on macOS 10.14 (Mojave) or earlier
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 follow ing line to the file:/- auto_nfs -nobrowse,nosuid

This w ill 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 follow ing format for each netw ork share that your Harmony database requires:

177

Chapter 2: Harmony Server/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 w ell as the first scene data storage space, named usadata000, and you haveanother scene data server called scenedataserver hosting the second scene data storage space,
named usadata001, you w ould need to add the follow ing 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 w ith /mnt/ are the folders w here you w ill mount your netw ork shares on yourw orkstation, referred to as mount points. Those folders must exist on your w orkstation and must
be empty. Hence, you must create them before you can try mounting those netw ork shares. First,
type the follow ing command to create the /mnt directory:$ sudo mkdir /mnt
6. Then, for each netw ork share you have, type in the follow ing command:$ sudo mkdir -m 777 /mnt/<share name>
7. Finally, since Harmony w ill 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 follow ing commandfor each netw ork 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. macOSw ill automatically attempt to mount the shares you configured as soon as any application tries toaccess them.

How to automatically mount Harmony database network shares using the Samba
protocol on macOS 10.14 (Mojave) or earlier
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 follow ing format:
smb://<server name>/USA_DB
For example, if your database server is named harmonyserver, you w ould type:smb://harmonyserver/USA_DB
3. Click Connect.

178Harmony 22 Installation Guide

4. In the authentication dialog, select w hether to connect as Guest or Registered User.
In the latter case, type in the name and passw ord of a user w ho has access to the netw ork shareand check Remember this password in my keychain to avoid having to authenticate again on
every log-in.
5. Click Connect.
A Finder w indow opens and displays the content of the netw ork share.
6. Repeat the process for every scene data share on your netw ork.
For example, if you have a scene data folder w ith number 000 on a server named harmonyserver,
and another one on a server named scenedataserver w ith the number 001, you w ould have toconnect to smb://harmonyserver/usadata000 andsmb://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 w indow s you opened, you can see the list of connected netw ork shares. Clickand drag each of the netw ork shares you just connected to from Finder and drag them to youruser’s list of Login Items.
This w ill make macOS connect to those netw ork shares automatically w hen logging in.
11. In a terminal, run the follow ing command for each netw ork share, w here <share name> is thename of the netw ork share.
$ sudo ln -s /Volumes/<share name> /<share name>For example, if you connected to netw ork shares named USA_DB, usadata000 and usadata001,
you w ould run the follow ing 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.

179

Chapter 2: Harmony Server

NOTES
Keep in mind the follow ing limitations to this method:l

Login items w ork on a per-user basis. You must perform the steps required to add
the netw ork shares to the user’s login items for every user account that w ill connect
to the database from the client.

l

If you need to sw itch from one user account to another, you must log out of the first
logged-in user before sw itching.
The reason for this is that if one user w ith these login items logs on, then a seconduser w ith the same login items logs on w ithout the first user logging out first, thenetw ork shares for that second user w ill be named differently. Hence, Harmony w ill
attempt to access the first user’s netw ork shares, but it w ill not be able to access itfrom the second user’s account.

l

If you installed the Harmony daemons using Harmony’s Configuration assistant,they w ill not be able to access the Harmony database unless you are logged in asuser 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 on page 83,
Running the W ebCC Server on Log-In on macOS on page 240 and Running the
Batch Processing Service on Log-In on macOS on page 312.

How to automatically mount Harmony database network shares using the Samba
protocol on macOS 10.15 (Catalina) or earlier
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 follow ing format:
smb://<server name>/USA_DB
For example, if your database server is named harmonyserver, you w ould type:smb://harmonyserver/USA_DB
3. Click Connect.
4. In the authentication dialog, select w hether to connect as Guest or Registered User.
In the latter case, type in the name and passw ord of a user w ho has access to the netw ork shareand check Remember this password in my keychain to avoid having to authenticate again on
every log-in.

180Harmony 22 Installation Guide

5. Click Connect.
A Finder w indow opens and displays the content of the netw ork share.
6. Repeat the process for every scene data share on your netw ork.
For example, if you have a scene data folder w ith number 000 on a server named harmonyserver,
and another one on a server named scenedataserver w ith the number 001, you w ould have toconnect to smb://harmonyserver/usadata000 andsmb://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 w indow s you opened, you can see the list of connected netw ork shares. Clickand drag each of the netw ork shares you just connected to from Finder and drag them to youruser’s list of Login Items.
This w ill make macOS connect to those netw ork shares automatically w hen logging in.
11. In a terminal, run the follow ing command for each netw ork share, w here <share name> is thename of the netw ork share.
$ sudo ln -s /Volumes/<share name> /<share name>For example, if you connected to netw ork shares named USA_DB, usadata000 and usadata001,
you w ould run the follow ing 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
12. Now , to configure Harmony to look for the mountpoints in /System/Volumes/Data, w e must
edit its shortcuts.conf configuration file. In a terminal, enter the follow ing command:$ sudo vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/shortcuts.conf"
13. At the top of the file, type the follow ing header line:
shortcut_list :14. Under shortcut_list :, add a line specifying the location of the mount point for each of themounted netw ork shares in the follow ing format:/<share name> /<full path to symlink to mount point>

181

Chapter 2: Harmony Server

In the example described above, this w ould result in the follow ing:
/USA_DB/System/Volumes/Data/USA_DB/usadata000 /System/Volumes/Data/usadata000/usadata001 /System/Volumes/Data/usadata001

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

NOTES
Keep in mind the follow ing limitations to this method:l

Login items w ork on a per-user basis. You must perform the steps required to add
the netw ork shares to the user’s login items for every user account that w ill connect
to the database from the client.

l

If you need to sw itch from one user account to another, you must log out of the first
logged-in user before sw itching.
The reason for this is that if one user w ith these login items logs on, then a seconduser w ith the same login items logs on w ithout the first user logging out first, thenetw ork shares for that second user w ill be named differently. Hence, Harmony w ill
attempt to access the first user’s netw ork shares, but it w ill not be able to access itfrom the second user’s account.

l

If you installed the Harmony daemons using Harmony’s Configuration assistant,they w ill not be able to access the Harmony database unless you are logged in asuser 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 on page 83,
Running the W ebCC Server on Log-In on macOS on page 240 and Running the
Batch Processing Service on Log-In on macOS on page 312.

182

Harmony 22 Installation Guide

Setting the User File Creation Permission Mask on macOS
By default, files created on macOS in directories that are accessible to everyone, such as Harmony database
directories, are created w ith a file permission mode that only allow s the ow ner (creator) of the file to modify
the file.
Since a Harmony database is a collaborative w ork environment w here everyone needs to be able to makechanges to scenes, this must be circumvented by setting the permission mask for file creation (referred to as
umask or user mask). By setting a permissive umask on your machine, all the files created by your client on the
Harmony database w ill be modifiable by anyone else w ith access to the database.
The method to change the user mask has changed as of Mac OS X 10.11. Below are the steps to accomplish
this depending on your version of macOS.

How to configure a permissive user mask on Mac OS X 10.11 and later
1. In a terminal, type the follow ing command:$ sudo launchctl config user umask 000
2. Reboot the machine.

How to configure a permissive user mask on Mac OS X 10.10 and earlier
1. In a terminal, type the follow ing command to edit your launchd configuration file:$ sudo vi /etc/launchd.conf
2. Add the follow ing line at the end of the file:umask 03. Save the file.
4. Reboot the machine.

183

Chapter 2: Harmony Server

Configuring the Hosts File for a macOS Client
W hen a client connects to a server using its hostname, it must first go through the netw ork in order to obtain
the IP address associated w ith that hostname, w hich adds overhead to the connection.
A hosts file is a configuration file w hich allow s you to forcefully associate certain hostnames w ith specific IP
addresses. This can allow you to set up a client machine to directly connect to the IP address of your Harmony
database server w ithout having to query the netw ork for its address first, w hich may increase netw ork
performance. How ever, this should only be done if your database server has a static IP address w hich you do
not intend to change. If the IP address of your server changes, the information in the host file w ill no longer be
accurate and you w ill be unable to connect to the server unless you update or remove the configuration in thehosts file.

How to associate the Harmony database server hostname to its IP address
1. In a terminal, open the hosts file for editing:$ sudo vi /etc/hosts
2. At the bottom of the file, add a new line.
3. Type in the permanent IP address of the Harmony database server follow ed by its hostname,separated by a space. For example, if your database server is named harmonyserver and its IP
address is 10.127.1.1, you w ould type in the follow ing:
10.127.1.1 harmonyserver
4. If your Harmony database server uses other machines for scene data storage, repeat for eachmachine used for the server so as to associate each machine's hostname to their permanent IP
address.
5. Save and quit.

184

Harmony 22 Installation Guide

About the Location of Mount Points on macOS
By default, Harmony database shares must be created and mounted at the root of the filesystem. If preferred,
it is possible to mount the database shares in different locations, and configure Harmony to look in theselocations instead. This is done by creating a shortcuts.conf configuration file for Harmony, w hich w ill
redirect requests to traditional database locations such as /USA_DB to a directory of your choosing on yourfilesystem.
The shortcuts.conf file must be located in the etc subfolder of the Harmony installation directory bydefault, but it can be located anyw here on your computer provided that you specify the location of this file in
the USA_DB_CONFIG environment variable. This can allow users to change the location of the Harmony
database server they are connecting to w ithout needing administrator privileges.

185

Chapter 2: Harmony Server

Configuring the Shortcuts File on macOSThe shortcuts.conf configuration file should be located in the etc subfolder of the Harmony installation
directory. It does not exist by default.

How to create and edit the shortcuts.conf configuration file
1. In a terminal, enter the follow ing command:$ vi "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/etc/shortcuts.conf"
This w ill create an empty shortcuts.conf file and open it in your command line interface text
editor.
2. At the top of the file, type the follow ing header line:
shortcut_list :3. Under shortcut_list :, add a line specifying the location of the mount point for USA_DB on
your filesystem in the follow ing format, <path_to_usa_db> is the absolute path to the mountpoint of USA_DB on your filesystem, w ithout a trailing slash, and including the USA_DB part:/USA_DB /<path_to_usa_db>

For example, if the mount point to USA_DB is a directory named USA_DB in/Users/jdoe/Documents, you w ould add this line:/USA_DB /Users/jdoe/Documents/USA_DB

4. For each scene data storage space used by the Harmony server, add a line in the same format. For
example, if your Harmony server has tw o scene storage spaces named usadata000 andusadata001, and their mount points are in the same directory as USA_DB, you w ould add thefollow ing lines:/usadata000 /Users/jdoe/Documents/usadata000/usadata001 /Users/jdoe/Documents/usadata001

5. Save and quit.
The next time you launch Harmony, it w ill look for the database files in the locations specified in
shortcuts.conf.

186

Harmony 22 Installation Guide

Setting a Custom Location for the Shortcuts Configuration File onmacOS
By default, shortcuts.conf should be located in Harmony's etc subfolder, w hich can only be modified byusers w ith administrator privileges. How ever, it is possible to specify a for shortcuts.conf in the USADB_CONFIG_FILE environment variable.
As a result, a user can place a shortcuts.conf file in their Documents folder and make Harmony read it,
w ithout requiring administrator privileges. Likew ise, an administrator can place the shortcuts.conf file in a
specific location that can be edited by any user, and set the environment variable to point to this file for allusers.

How to set a custom location for the shortcuts.conf file
1. First, create a shortcuts.conf configuration file in the preferred location—see Configuring the
Shortcuts File on macOS.
2. Then, do one of the follow ing:l

If you w ant to set the location of shortcuts.conf for your user only, enter the follow ing
command in a terminal:$ vi ~/.bash_profilel

If you w ant to set the location of shortcuts.conf for all users, enter the follow ing
command in a terminal:$ sudo vi /etc/profile

You are now editing a script that either runs w hen your user logs in, or w hen your machine boots.
3. At the end of the script, add the follow ing lines, replacing <path to shortcuts.conf> w ith theabsolute (full) path to the shortcuts.conf file you created:
export USADB_CONFIG_FILE="<path to shortcuts.conf>"
launchctl setenv USADB_CONFIG_FILE "<path to shortcuts.conf>"

4. Save and quit.
5. Reboot.

187

Chapter 2: Harmony Server

Configuring Harmony Server Clients on GNU/LinuxOn macOS and GNU/Linux, a client w orkstation is configured to connect to a Harmony server by mounting thedifferent netw ork shares used for the database on directories w ith the same name as these shares, at the rootof the filesystem. As a result, all of the database and scene data files become part of your machine's filesystem, and the path to each file in your database is the same path on both the client machine and the servermachine, allow ing seamless access to all of your scene data on any machine. The most straightforw ard
approach to this is to configure these shares to be automatically mounted on boot using the file system table(fstab) file.
Connecting a GNU/Linux Client to a Database Server

189

Setting the User File Creation Permission Mask on macOS

191

Configuring the Hosts File for a GNU/Linux Client

193

About the Location of Mount Points on GNU/Linux

194

Configuring the Shortcuts File on GNU/Linux

195

Setting a Custom Location for the Shortcuts Configuration File on GNU/Linux

196

188

Harmony 22 Installation Guide

Connecting a GNU/Linux Client to a Database Server
The most simple w ay of connecting a GNU/Linux client to a Harmony database server is by mounting thedatabase netw ork shares using the NFS protocol. This can be done automatically on boot by adding entries foreach database netw ork share in the file system table (fstab).

How to mount Harmony database network shares using the file system table
1. In a terminal, enable the NFS and NFS lock daemons:$ sudo chkconfig nfs on$ sudo service nfs start$ sudo chkconfig nfslock on$ sudo service nfs start
1. Open the file system table for editing:$ sudo vi /etc/fstab
2. Add an entry in the follow ing format for each netw ork share that your Harmony database requires:<server name>:/<share name> /<share name> nfs rw,soft,intr,bg 0 0
For example, if your server is named harmonyserver and hosts the database files (USA_DB) as w ellas 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
w ould need to add the follow ing lines:
harmonyserver:/USA_DB/USA_DBnfs rw,soft,intr,bg 0
harmonyserver:/usadata000/usadata000 nfs rw,soft,intr,bg 0
scenedataserver:/usadata001 /usadata001 nfs rw,soft,intr,bg 0000

3. Create a mount point at the root of your filesystem for each share that you intend to mount:$ sudo mkdir -m 777 /<share name 1> /<share name 2> /<share name 3>
For example, the mount points for the fstab entries in the previous examples w ould be created w ith
this command:$ sudo mkdir -m 777 /USA_DB /usadata000 /usadata001
4. Attempt to mount the new fstab entries w ith the follow ing command:$ sudo mount -a
There w ill be no output if the command w as successful.
5. Verify that you can view the files in each mounted share w ith the follow ing command:$ ls /<share name>For example:

189Chapter 2: Harmony Server$ ls /USA_DB$ ls /usadata000$ ls /usadata001
If you can see the database files in your client filesystem, you can now launch Harmony or any
other Harmony application and connect to the database.

190

Harmony 22 Installation Guide

Setting the User File Creation Permission Mask on macOS
By default, files created on GNU/Linux in directories that are accessible to everyone, such as Harmony
database directories, are created w ith a file permission mode that only allow s the ow ner (creator) of the fileand the group they belong to to modify the file.
Since a Harmony database is a collaborative w ork environment w here everyone needs to be able to makechanges to scenes, this must be circumvented by setting the permission mask for file creation (referred to as
umask or user mask). By setting a permissive umask on your machine, all the files created by your client on the
Harmony database w ill be modifiable by anyone else w ith access to the database.
On GNU/Linux, you can make sure the user mask is alw ays permissive by making it permissive every time you
log in. This is done by adding the command to set the user mask in a log-in script. You can choose w hether to
use the log-in script for all users or the one for your current user only.

How to configure a permissive user mask for all users on GNU/Linux
1. In a terminal, edit the login script for all users logging in through the Bash shell w ith the follow ing
command:$ sudo vi /etc/bashrc
2. In the script file, find the follow ing block:# By default, we want umask to get set. This sets it for non-login shell.
# Current threshold for system reserved uid/gids is 200# You could check uidgid reservation validity in# /usr/share/doc/setup-*/uidgid fileif [ $UID -gt 199 ] && [ "`/usr/bin/id -gn`" = "`/usr/bin/id -un`" ]; thenumask 002
else
umask 022fi

3. In the block, replace umask 002 w ith umask 000:
# By default, we want umask to get set. This sets it for non-login shell.
# Current threshold for system reserved uid/gids is 200# You could check uidgid reservation validity in# /usr/share/doc/setup-*/uidgid fileif [ $UID -gt 199 ] && [ "`/usr/bin/id -gn`" = "`/usr/bin/id -un`" ]; thenumask 000
else
umask 022fi

4. Save and quit.
5. Create a umask script for all users logging in through a CSH shell w ith the follow ing command:

191

Chapter 2: Harmony Server$ sudo vi /etc/csh.cshrc
6. In the script file, find the follow ing block:# By default, we want this to get set.
# Even for non-interactive, non-login shells.
# Current threshold for system reserved uid/gids is 200# You could check uidgid reservation validity in# /usr/share/doc/setup-*/uidgid fileif ($uid > 199 && "`/usr/bin/id -gn`" == "`/usr/bin/id -un`") thenumask 002
else
umask 022
endif

7. In this block, replace umask 002 w ith umask 000:
# By default, we want this to get set.
# Even for non-interactive, non-login shells.
# Current threshold for system reserved uid/gids is 200# You could check uidgid reservation validity in# /usr/share/doc/setup-*/uidgid fileif ($uid > 199 && "`/usr/bin/id -gn`" == "`/usr/bin/id -un`") thenumask 000
else
umask 022
endif

How to configure a permissive user mask for the current user on GNU/Linux
1. In a terminal, open your Bash log-in script for editing w ith the follow ing command:$ vi ~/.bashrc
2. Add the end of the log-in script, add the follow ing command:
umask 03. Save and quit.
4. Open your CSH log-in script for editing w ith the follow ing command:$ vi ~/.cshrc
5. Add the end of the log-in script, add the follow ing command:
umask 0192

Harmony 22 Installation Guide

Configuring the Hosts File for a GNU/Linux Client
W hen a client connects to a server using its hostname, it must first go through the netw ork in order to obtain
the IP address associated w ith that hostname, w hich adds overhead to the connection.
A hosts file is a configuration file w hich allow s you to forcefully associate certain hostnames w ith specific IP
addresses. This can allow you to set up a client machine to directly connect to the IP address of your Harmony
database server w ithout having to query the netw ork for its address first, w hich may increase netw ork
performance. How ever, this should only be done if your database server has a static IP address w hich you do
not intend to change. If the IP address of your server changes, the information in the host file w ill no longer be
accurate and you w ill be unable to connect to the server unless you update or remove the configuration in thehosts file.

How to associate the Harmony database server hostname to its IP address
1. In a terminal, open the hosts file for editing:sudo vi /etc/hosts
2. At the bottom of the file, add a new line.
3. Type in the permanent IP address of the Harmony database server follow ed by its hostname,separated by a space. For example, if your database server is named harmonyserver and its IP
address is 10.127.1.1, you w ould type in the follow ing:
10.127.1.1 harmonyserver
4. If your Harmony database server uses other machines for scene data storage, repeat for eachmachine used for the server so as to associate each machine's hostname to their permanent IP
address.
5. Save and quit.

193

Chapter 2: Harmony Server

About the Location of Mount Points on GNU/LinuxBy default, Harmony database shares must be created and mounted at the root of the filesystem. If preferred,
it is possible to mount the database shares in different locations, and configure Harmony to look in theselocations instead. This is done by creating a shortcuts.conf configuration file for Harmony, w hich w ill
redirect requests to traditional database locations such as /USA_DB to a directory of your choosing on yourfilesystem.
The shortcuts.conf file must be located in the etc subfolder of the Harmony installation directory bydefault, but it can be located anyw here on your computer provided that you specify the location of this file in
the USA_DB_CONFIG environment variable. This can allow users to change the location of the Harmony
database server they are connecting to w ithout needing administrator privileges.

194

Harmony 22 Installation Guide

Configuring the Shortcuts File on GNU/LinuxThe shortcuts.conf configuration file should be located in the etc subfolder of the Harmony installation
directory. It does not exist by default.

How to create and edit the shortcuts.conf configuration file
1. In a terminal, enter the follow ing command:$ vi /usr/local/ToonBoomAnimation/harmony[Edition]_
22/etc/shortcuts.conf
This w ill create an empty shortcuts.conf file and open it in your command line interface text
editor.
2. At the top of the file, type the follow ing header line:
shortcut_list :3. Under shortcut_list :, add a line specifying the location of the mount point for USA_DB on
your filesystem in the follow ing format, <path_to_usa_db> is the absolute path to the mountpoint of USA_DB on your filesystem, w ithout a trailing slash, and including the USA_DB part:/USA_DB /<path_to_usa_db>

For example, if the mount point to USA_DB is a directory named USA_DB in /home/jdoe, you
w ould add this line:/USA_DB /home/jdoe/USA_DB

4. For each scene data storage space used by the Harmony server, add a line in the same format. For
example, if your Harmony server has tw o scene storage spaces named usadata000 andusadata001, and their mount points are in the same directory as USA_DB, you w ould add thefollow ing lines:/usadata000 /home/jdoe/usadata000/usadata001 /home/jdoe/usadata001

5. Save and quit.
The next time you launch Harmony, it w ill look for the database files in the locations specified in
shortcuts.conf.

195

Chapter 2: Harmony Server

Setting a Custom Location for the Shortcuts Configuration File on
GNU/Linux
By default, shortcuts.conf should be located in Harmony's etc subfolder, w hich can only be modified byusers w ith administrator privileges. How ever, it is possible to specify a for shortcuts.conf in the USADB_CONFIG_FILE environment variable.
As a result, a user can place a shortcuts.conf file in their Documents folder and make Harmony read it,
w ithout requiring administrator privileges. Likew ise, an administrator can place the shortcuts.conf file in a
specific location that can be edited by any user, and set the environment variable to point to this file for allusers.
On GNU/Linux, it is common to set environment variables for both the Bash and CSH shells, so that they may
be used interchangeably. The follow ing steps cover how to do both.

How to set a custom location for the shortcuts.conf file
1. First, create a shortcuts.conf configuration file in the preferred location—see Configuring the
Shortcuts File on GNU/Linux.
2. Then, do one of the follow ing:l

If you are setting the location of shortcuts.conf for your user only, enter the follow ing
command in a terminal to edit the Bash script that runs w hen you log in:$ vi ~/.bash_profilel

If you are setting the location of shortcuts.conf for all users, enter the follow ing
command in a terminal to edit the Bash script that runs w hen any user logs in:$ sudo vi /etc/profile

3. At the end of the script, add the follow ing line, replacing <path to shortcuts.conf> w ith theabsolute (full) path to the shortcuts.conf file you created:
export USADB_CONFIG_FILE="<path to shortcuts.conf>"

4. Save and quit.
5. Do one of the follow ing:l

If you are setting the location of shortcuts.conf for your user only, enter the follow ing
command in a terminal to edit the CSH script that runs w hen you log in:$ vi ~/.login

196

Harmony 22 Installation Guidel

If you are setting the location of shortcuts.conf for all users, enter the follow ing
command in a terminal to edit the CSH script that runs w hen any user logs in:$ sudo vi /etc/csh.login

6. At the end of the script, add the follow ing line, replacing <path to shortcuts.conf> w ith theabsolute (full) path to the shortcuts.conf file you created:
setenv USADB_CONFIG_FILE "<path to shortcuts.conf>"

7. Reboot.

197

Chapter 2: Harmony Server

Harmony Server Configuration
This section w ill instruct you on how to configure a Harmony database server.
Using Unicode Characters in Harmony

199

Enabling Unicode Characters in Environment, Job and Scene Names

200

Enabling Unicode in Layer/Node Names

201

Configuring Scene Resolution Presets for aHarmony Database202

Configuring Resolution Presets for Environments or Jobs

204

About Resolution Presets in XML Format

205

198

Harmony 22 Installation Guide

Using Unicode Characters in Harmony
By default, Harmony w ill only allow you to use the follow ing characters in environment, job, scene and layer
names:l

Small and capital letters in the Latin alphabet, excluding accented lettersl

Numbersl

Dashes (-), underscores (_), plus signs (+) and equal signs (=)

It is possible, how ever, to enable the use of most of the characters in the Unicode character range. How ever,this feature has important limitations that must be taken in account:lmacOS and GNU/Linux machines cannot communicate in Unicode characters over the NFS protocol.
Even w hen using Unicode, characters for certain languages use different encoding on GNU/Linux andmacOS. W hile the Samba file sharing protocol can interpret these differences in encoding in the backend, NFS does not. Hence, for a macOS server to server GNU/Linux clients or for a GNU/Linux server toserver a macOS client, you must either use the Samba protocol to share files, or keep Unicode disabled.

l

Scenes w ith Unicode characters in their names cannot be opened from W ebCC.

l

A scene w ith Unicode characters in its name that has been exported from a W ebCC server cannot be
updated on the client side using the Dow nload Database Changes command and cannot be updated on
the server side using the Update Database Scene command.

l

The Unity engine does not support Unicode characters. Unicode characters should not be used w hen
using Harmony for gaming.

lUnicode characters should not be used in the names of the root folders of the database file systems (ie:
USA_DB, usadata000, etc.)l

Zip archives may encounter issues w ith Unicode characters. It is recommended to use the 7z archiving
format w hen archiving database files or scene data.

199

Chapter 2: Harmony Server

Enabling Unicode Characters in Environment, Job and Scene Names
You can enable Unicode characters in Control Center, allow ing you to create environments, jobs and scenes
w ith names containing Unicode characters.

IMPORTANT
Before enabling Unicode characters for your Harmony database, please see Using Unicode
Characters in Harmony to learn about the limitations of Harmony regarding Unicode characters.

How to enable Unicode characters in Control Center
1. In the top menu, select Admin and check the Allow Unicode Names option.

200

Harmony 22 Installation Guide

Enabling Unicode in Layer/Node Names
To enable the use of Unicode characters in the names of layers and nodes, you must enable the Allow Unicode
Names preference in Harmony.

How to enable Unicode characters in Harmony
1. In the top menu, select Edit (W indows/Linux) or Harmony [Edition] (macOS) > Preferences.
The Preferences dialog opens.
2. Open the Advanced tab.
3. Check the Allow Unicode Names preference.
4. Click on OK.

201

Chapter 2: Harmony Server

Configuring Scene Resolution Presets for aHarmony Database
W hen you create a new database, by default, Harmony's resolution presets are copied to it. These resolution
presets can be used by all users of the database:This file can be found at the follow ing location, and can be edited:/USA_DB/resolution/resolution.conf
If you open the file, you w ill see some comment lines starting w ith #, follow ed by definitions of the resolution
presets, like those in the example below :## resolution.conf for Harmony Premium## This file defines the scene resolutions available to the program.
## The default version of this file can be found in "/usa/etc" for old Harmony/Opus# or in "<Application Folder>/etc" for Harmony/Animate/Digital Pro/Storyboard.
## You may copy this file to /USA_DB/jobs/your_jobs for job specific resolutions# or /USA_DB/environments/your_environment for environment wide resolutions or /USA_DB/resolution/# for system wide resolutions. In the case of /USA_DB/resolution/ you will have to create a folder# resolution if it doesn't exist already.
## You may add any resolution to this file that you frequently use in your scenes.### syntax:#
resolution <name> <x> <y> [custom] [fps <fps>] [<fov>] [<projection>]## The "custom" keyword means that this resolution was created by a user.
## The "fps" keyword can be followed by an integer to specify the number of frames per second.
## <fov> is either a "V" for vertical fitting, an "H" for horizontal fitting, or an angle expressed# in degrees that specifies a custom field of view. If unspecified, horizontal fitting is used.
## <projection> is either "Perspective" or "Orthographic" and is available only in Harmony# Premium. If unspecified, a perspective projection is used.
#202Harmony 22 Installation Guide

default HDTV_1080p24
resolution HDTV_1080p24
resolution HDTV_1080p25
resolution HDTV_720p24
resolution 4K_UHD
resolution 8K_UHD

1920 1080 fps 24 V
1920 1080 fps 25 V
1280 720 fps 24 V
3840 2160 fps 24 V
7680 4320 fps 24 V

As you can see, after the comments, the first line of the file defines w hich resolution is the default resolution.
The default resolution is the resolution new scenes are created w ith.
default <resolution name>Then, each line is used to define one resolution preset, in this format:
resolution <resolution name> <width> <height> fps <frame rate> <field of view> <projection>l

The <resolution name> is the name of the resolution. This is used to select the resolution preset in
the Scene Settings dialog, the default resolution and the resolution in w hich to render a scene.

l

The <width> and <height> are the dimensions of the scene, in pixels.

l

The <frame rate> is the amount of frames to play per second.

l

The <field of view> is the angle of the camera lense. It can be set to V to make the camera cone fit
the height of the camera field, to H to make the camera cone fit the w idth of the camera field, or to anangle in degrees. If unspecified, the field of view is made to fit horizontally.

l

The <projection> is how elements are projected in the 3D space. It can either be Perspective or
Orthographic. If unspecified, the projection w ill be set to Perspective.

NOTE
Orthographic projection is only available in Harmony Premium.

Additionally, you can add the custom keyw ord just before fps to specify that this resolution is user-created.

203

Chapter 2: Harmony Server

Configuring Resolution Presets for Environments or Jobs
It is possible to create resolution preset lists specifically for environment and for jobs. This allow s you to makecertain resolution presets only available if the scene is for a project that is appropriate for it. To do this, simply
create a resolution presets file, either in regular format or XML format, in the appropriate location:l

To create a resolution presets list for an environment, create the list in:/USA_DB/environments/<environment name>/resolution.conf,
Replace <environment name> w ith the name of the environment.

l

To create a resolution presets list for a job, create the list in:/USA_DB/db_jobs/<job name>/resolution.conf
Replace <job name> w ith the name of the job.

NOTE
You can also name the file resolution.xml and create your resolution presets in XML format—
see About Resolution Presets in XML Format.

If several resolution preset lists are available for a scene, for example, if the scene's job, the scene's
environment and the database all have their ow n resolution preset lists, all those lists w ill be combined,making all of the presets in all of these lists available for the scene.
If the same preset is present in tw o resolution preset lists, it w ill only appear once in the list of available
resolution presets, so there w ill not be any duplicate.
If a preset w ith the same name, but different properties, is listed in more than one of the resolution presets
lists, the one at the low est level w ill be used. For example, if the resolution preset lists for the scene's job, its
environment and its database all contain a preset named 4K, the preset for the scene's job w ill be used. If thepreset is only in the scene's environment presets list and in database presets list, the one in the environment's
presets list w ill be used.
If you do not w ant to have scene presets that can be used across all environments and jobs, you can delete theresolution presets file for your database. W hen you open a scene, Harmony w ill automatically look for a
resolution presets file for the database, for the scene's environment and for the scene's job. If it finds a
resolution presets in any of these locations, it w ill use it. If it does not find resolution presets in any of thesethree locations, it w ill display the follow ing error message:204

Harmony 22 Installation Guide

About Resolution Presets in XML Format
By default, resolution presets used by Harmony are stored in a file named resolution.conf w hich defines
each preset using a very basic format, w here each preset is defined using a line, and each of its properties are
separated by spaces.
If you edit or create a resolution preset in Harmony, your resolution presets file w ill be saved as
resolution.xml, in the same directory, and the presets w ill be defined in XML format. From that point on,
the resolution.conf file w ill be ignored. Therefore, if you w ant to manually edit your resolution presets fora database, an environment or a job, and the corresponding directory contains both a resolution.conf anda resolution.xmlfile, you must edit the resolution.xml file.
The resolution.xml file is formatted like in the example below :<!DOCTYPE resolutions><!--This file defines the scene resolutions available to the program.--><!--The default version of this file can be found in "<Application Folder>/etc" --><!--You may copy this file to /USA_DB/jobs/your_job for job specific resolutions--><!--or /USA_DB/environments/your_environment for environment wide resolutions.--><!--You may add any resolution to this file that you frequently use in your scenes.--><!----><!--The syntax follows standard xml format, which each tag followed by its value.--><!--The "custom" keyword means that this resolution was created by a user.--><!--The "FPS" keyword specifies the number of frames per second.--><!--The "fovFit" specifies the field of view. It is either vertical, horizontal, or custom, with the<!--as an angle in degrees that specifies a custom field of view. If unspecified, horizontal fitting<!--The "projectionType" is either "perspective" or "orthographic". If unspecified, a perspective pro<resolutions><default name="HDTV_1080p24"/><resolution FPS="24" fovFit="vertical" projectionType="perspective" resX="1920" resY="1080" name=<resolution FPS="25" fovFit="vertical" projectionType="perspective" resX="1920" resY="1080" name=<resolution FPS="24" fovFit="vertical" projectionType="perspective" resX="1280" resY="720" name="<resolution FPS="24" fovFit="vertical" projectionType="perspective" resX="3840" resY="2160" name=<resolution FPS="24" fovFit="vertical" projectionType="perspective" resX="7680" resY="4320" name=<resolution FPS="24" fovFit="vertical" projectionType="perspective" resX="2048" resY="1080" name=<resolution FPS="24" fovFit="vertical" projectionType="perspective" resX="4096" resY="2160" name=</resolutions>

As you can see, its format is very similar to resolution.conf, except that it uses an XML structure constructed
like so:<!DOCTYPE resolutions><resolutions><!--Resolution presets go here--></resolutions>

Inside the <resolutions> block, the first line is a <default> tag, w hich defines the default resolution
preset to use w hen creating a scene, in this format:<default name="preset name"/>205

Chapter 2: Harmony Server

Then, each <resolution> tag defines a single resolution preset, in this format:<resolution FPS="frame rate" fovFit="field of view" projectionType="projection type" resX="width"

Similar to the lines in resolution.conf, each <resolution> tag contains the follow ing attributes:l

FPS: The amount of frames to play per second.

lfovFit: The angle of the camera lense. It can be set to vertical to make the camera cone fit theheight of the camera field, to horizontal to make the camera cone fit the w idth of the camera field, orto an angle in degrees. If unspecified, the field of view is made to fit horizontally.

lprojectionType: How elements are projected in the 3D space. It can either be perspective or
orthographic. If unspecified, the projection w ill be set to perspective.

NOTE
Orthographic projection is only available in Harmony Premium.

lresX: The w idth of the scene in pixels.

lresY: The height of the scene in pixels.

l

name: The name of the resolution. This is used to select the resolution preset in the Scene Settings
dialog, the default resolution and the resolution in w hich to render a scene.

206Harmony 22 Installation Guide

207

Chapter 3: W ebCC

Chapter 3: W ebCC
W ebCC is a w eb server suite that essentially allow s you to host your Harmony database on the Internet,
letting freelancers and off-site contributors w ork on your production from any location w ith Internet access.
Users can brow se your Harmony database using a w eb brow ser, dow nload scenes, w ork on the dow nloaded
scenes locally using their copy of Harmony, then upload their changes back to the database.
Because it is entirely w eb-based, W ebCC users do not need to be directly connected to the Harmony server
nor to have a Harmony Server license to use W ebCC. All they need is a w eb brow ser, as w ell as a licensed
copy of Harmony Stand Alone to w ork on the scenes they dow nload.
W ebCC can how ever also be used on machines that are connected to the Harmony database server, as acomplement to Control Center. In this case, scenes can be opened directly from W ebCC in Harmony, w ithout
having to dow nload them first.

208

Harmony 22 Installation Guide

W ebCC Server Installation
One of the first things you must know before configuring a W ebCC server is that a W ebCC server in itself is
not a database server, but rather, an addition to a database server. Hence, if you have not already done so, you
should follow the steps to create a Harmony database server—see About Database Server Installation on
page 49.
Once your Harmony database server is configured, configuring a W ebCC server is relatively straightforw ard.
The file structure for the W ebCC server is already included in the Harmony installation directory and is readyto use. As soon as you launch the W ebCC service on a machine that has access to the database and allow
connections to it to go through the firew all, it is already possible to connect to W ebCC using a w eb brow seron any machine on the site.

NOTES
l

To optimize both security and performance, it may be useful to set up W ebCC for internal
netw ork access only on the same machine that acts as the Harmony database server, and theninstall W ebCC for W orld W ide W eb access on a dedicated W eb server. W ith this approach,
you do not have to give access to the database server to the W eb.

l

The follow ing instructions w ill explain how to set up a W ebCC server w hich w ill be accessible
on-site, but w ill not explain how to make the server accessible off-site.

209

Chapter 3: W ebCC

Installing W ebCC on W indows
On W indow s, installing a W ebCC server w ith the default parameters can easily be done using theConfiguration W izard.
Disabling the Firewall for a W ebCC Server on W indows

211

Installing the W ebCC Service on W indows

212

Running the Database Server Service on Log- In on W indows

213

Configuring W ebCC with Custom Parameters on W indows

215

About SSL, HTTPS and W ebCC on W indows

220

Configuring W ebCC to Use SSL on W indow s

221

Setting Up Static IPs for W ebCC on W indows

225

Opening the Firewall Ports for a Harmony W ebCC Server on W indows

229

Checking the W ebCC Server Log on W indows

231

Launching the W ebCC Server Manually on W indows

232

Stopping and Restarting the W ebCC Server on W indows

233

Uninstalling the W ebCC Server on W indows

235

210

Harmony 22 Installation Guide

Disabling the Firewall for a W ebCC Server on W indows
By default, the W indow s firew all w ill block incoming connections to a W ebCC server. This installation guideprovides instructions on how to add exceptions for the W ebCC server to your firew all. How ever, you may
prefer to disable the firew all completely so as to simplify the installation process or to rule out the firew all as
a possible cause w hen troubleshooting an issue.

IMPORTANT
If you choose to disable the firew all on W indow s, it is critical to ensure that your domain has
effective site-w ide security measures to prevent unauthorized access to your W ebCC server.

How to disable the firewall on W indows
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, select System and Security.
3. Under W indows Defender Firewall, select Check firewall status.
4. In the list to the left, select Turn W indows Defender Firewall on or off.
5. Under Domain network settings, select Turn off W indows Defender Firewall (notrecommended).
6. Under Private network settings, select Turn off W indows Defender Firewall (notrecommended).
7. Under Public network settings, select Turn off W indows Defender Firewall (not recommended).
8. Click on OK.

211

Chapter 3: W ebCC

Installing the W ebCC Service on W indows
You can easily install W ebCC as a W indow s service using the Configuration W izard. It w ill launch as soon as
the machine boots, under user usabatch.

NOTE
The follow ing steps indicate how to make the W ebCC server service launch on boot, via the user
usabatch, w ho w ill have administrator privileges. If you prefer, you can make the database serverlaunch on log-in as the logged-in user. For more information, see Running the Database Server on
Log-In on macOS on page 83.

How to install the W ebCC service
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
3. In the list of tasks, right of Harmony W eb Control Center Server, click on ....
4. In the ensuing dialog, under Do you wish to install the Harmony W eb Control Center Server?,select Yes.
5. Click on Next.
6. Click on Finish to confirm the changes.
The W ebCC service is now installed and should be running. You can test that it w orks by launchinga w eb brow ser and going to the follow ing address:
http://localhost:8080/

212

Harmony 22 Installation Guide

Running the Database Server Service on Log- In on W indows
The traditional w ay of running a W ebCC server is by running the server as a W indow s service. This means it
launches and allow s clients to connect as soon as the machine is booted, w ithout any user being signed-in.
Using Service Launcher, it is possible to configure your W ebCC server to only launch as the currently loggedin user, w hen they log in. This means that W ebCC w ill only be accessible if the user configured to run it islogged in.
Although this may seem impractical, it may be preferable for security reasons. Services installed w ith theConfiguration W izard are run under the user usabatch, an user w ith administrator privileges w hich is createdby Configuration W izard to launch the services. W hen using Service Launcher, the logged-in user does notneed to have administrator privileges to run services.
Before configuring Service Launcher to run the W ebCC server, the w indow s service that launches it must be
disabled, so as to avoid launching tw o instances of the W ebCC server simultaneously.

NOTE
W hile W indow s services run regardless of w ho is logged in and even w hen no user is logged-in,
Service Launcher w ill only run w hen the use for w hich it w as specifically configured is logged in.
This means that if you w ant Service Launcher to launch w hen any user is logged in, you must
configure it for each user that has access to the machine.

How to disable the W ebCC server service
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on Remove.
From that point on, the W ebCC server service w ill no longer launch on boot.
6. Close the Control Panel.

213

Chapter 3: W ebCC

How to configure the W ebCC server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

2. Do one of the follow ing:l

If Service Launcher is not running, open the Start menu and, in the Programs list, selectHarmony 22 [Edition] > Tools >lService Launcher.

If Service Launcher is already running, click on its iconin the notification tray.

The Service Launcher application launches.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the W ebCC tab.
5. Check the Launch when Service Launcher starts option.
6. To make sure users must enter their passw ord w hen logging in to W ebCC, check the
Authentication option.
7. By default, W ebCC w ill use port 8080. If you w ant to use a specific port to connect to W ebCC, type
it in the Port field.
8. Click on Launch to verify that W ebCC launches successfully through Service Launcher using theselected parameters.
9. In the top menu, select Server > Save All Settings.
From now on, the W ebCC server w ill launch through Service Launcher w hen you log in.

NOTE
You can enter parameters in the Other Parameters field to customize the W ebCC server. For
more information, see Configuring W ebCC w ith Custom Parameters on W indow s on page
215

214

Harmony 22 Installation Guide

Configuring W ebCC with Custom Parameters on W indows
W ebCC can run w ith no parameters, but it also provides some customization options. Among other things, you
can change the port number, adjust its security settings and configure it to run w ith SSL security.
If you installed W ebCC as a W indow s service, you can customize its parameters by modifying its commandline in the Harmony Control Panel. If you use Service Launcher to run W ebCC, you can easily add parametersin the Other Parameters field of the W ebCC tab of Service Launcher.

TIP
You can also configure W ebCC to run a custom script or executable every time a user updates ascene, w hether by importing it or by updating it from Harmony. To do this, on the W ebCC server,
set the environment variable WEBCC_POST_IMPORT_SCRIPT to the path of a script or executablethat you w ant to be launched each time a scene is updated. The script or executable w ill belaunched w ith the environment, job and scene name as its command line parameters, in that order.

How to stop the W ebCC server service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on the Command Line field and press the End key to move the text cursor after webcc.bat.
6. After webcc.bat, add a space, then type each parameter you w ant to add, separated by spaces.
For example, if you w ant W ebCC to use the port number 8081, you w ould edit the line like so:
C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22 [Edition]\win64\bin\webcc.bat

NOTE
For a list of parameters and their usage, see W ebCC Parameters Table on page 216.

215

Chapter 3: W ebCC

7. Click on Update parameters to save the command line parameters.
8. Click on Start to restart W ebCC.

How to add parameters for W ebCC in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. If you w ant to let any user connect to W ebCC w ithout credentials and have administrative
privileges, uncheck the Authentication option. Otherw ise, make sure it is checked.
5. If you w ant to change the port used by the W ebCC server, type the desired port number in the Port
field.
6. If you w ant to specify any other option, type them in the Other Parameters field, separated by
spaces.

NOTE
For a list of parameters and their usage, see W ebCC Parameters Table on page 216.

7. In the top menu, select Server > Save All Settings.
8. Click on the Stop button.
9. Click on the Launch button.

W ebCC Parameters Table
The follow ing is a table of parameters that can be specified to customize the behaviour of your W ebCC server.
They can be used in both the W ebCC shell script and in Service Launcher.
Parameter

Description-numWorkers <number>

The amount of server nodes to launch to process client requests. Each noderequires one CPU core, and a single node can only process one client request at atime. Therefore, the more nodes are launched, the less likely the server is to stallunder heavy load.
If this parameter is not specified, W ebCC w ill use as many nodes as there are
CPU cores on the server.

216

Harmony 22 Installation Guide

Parameter

Description-noAuthDisables authentication. W ith this option enabled, any user accessing the W ebCC
w eb interface w ill be logged in as usabatch and w ill administrative privileges on
the entire database.

The port to w hich W ebCC is deployed.
The default port for accessing W ebCC is 8080. For brow sers to access W ebCC
w ithout specifying the port number, you can use port 80.
-port <port number>

NOTE
If either the -http or -https parameter is specified, the -port parameterw ill be ignored.

-exchange<directory>

The location of the exchange directory on the local filesystem. This directory is
w here all packages are stored w hen exporting or importing scenes.
By default, this directory is /USA_DB/exchange.

-cacheDuration<seconds>

The amount of seconds to keep data in the cache. This can be set to any value
betw een 1 and 999999. By default, this is set to 3600.

Enables cross-origin resource sharing on the W ebCC server.

-allowAllOrigin

By default, as a standard security measure, only files on the same server as theW ebCC server are allow ed to use W ebCC resources. W ith this option enabled, it
is possible to create w eb interfaces on other servers that use resources stored on
the W ebCC server, or to store different modules of W ebCC on different servers
and let them communicate together.
In most use cases, this option should be disabled to prevent other machines from
exploiting resources on the W ebCC server.

-disableAnalytics

Disables Google Analytics tracking for all clients. By default, this is enabled.

Overrides a default permission for the given user type.
-permission <usertype> <action><on|off>

At the moment, this parameter can only be used for the user type animator andfor the permission import_export_any_scene. Hence, w hen used w ith thefollow ing syntax, animator-type users can export and import any scene in the
database, w ithout requiring the scene to be assigned to them first.
-permission animator import_export_any_scene on217

Chapter 3: W ebCC

HTTPS/SSL Parameters Table
The follow ing parameters can be used to enable and configure SSL for your W ebCC server.

NOTE
For more information on how to configure W ebCC w ith SSL, see About SSL, HTTPS and W ebCC
on W indow s on page 220.

Parameter

Description

Enables connection to the server through the https protocol using the specified
port number.

-https <port number>

A commonly used port for accessing W ebCC through the https protocol is 8443.
For w eb brow sers to access W ebCC via https w ithout specifying the port
number—provided that the address of the server is preceded by https://—youcan use port 443.
For https to w ork, you must either specify a pair of PEM format key and certificate
w ith the -key and -cert option, or a PFX format certificate w ith the -pfx
option.

If access through the https protocol is enabled, this parameter allow s you to also
allow access through the http protocol through the specified port.

-http <port number>

Using this parameter is optional. If the -https parameter is specified, but not the-http parameter, W ebCC w ill only accept connections through https.
The default port for accessing W ebCC through the http protocol is 8080. Forbrow sers to access W ebCC via http w ithout specifying the port number, you can
use port 80.

The location of the private key file for the SSL session. This must be specified
along w ith the -cert parameter.
-key <key file>

The private key must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the key is encoded in Base64 and located betw een -----BEGIN
PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private
keys in this format have a .key extension.

The location of the security certificate file for the SSL session. This must be
specified along w ith the -key parameter.
-cert <certificate
file>

The certificate must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the certificate is encoded in Base64 and located betw een ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
Typically, such certificates have a .crt, .cer or .pem extension.

218

Harmony 22 Installation Guide

Parameter

Description-pfx <pfx certificate
file>

If you have a Personal Information Exchange (PFX) certificate, you can use thisparameter to specify its location, instead of using a PEM certificate and key.
Typically, such certificates have a .pfx or .p12 extension. Since thesecertificates include their ow n private key, specifying a key w ith this certificate type
is not required.

If you have a domain certificate that is signed by a certificate authority (CA), thisparameter allow s you to specify the root CA certificate and/or its intermediate
certificates.
If you w ant to specify several certificates so as to compose the chain going fromyour domain certificate to the root CA certificate, you can repeat the parameter,like so:-ca <intermediate certificate 1> -ca <intermediate
certificate 2> -ca <root CA certificate>-ca <root ca
certificate file>

Typically, you w ill be able to log on to W ebCC using SSL from a W eb brow sereven if W ebCC is only configured w ith your domain certificate, provided that it issigned by a reputable certificate authority. How ever, if you w ant project
collaborators to be able to use the Download Database Changes and Update
Database Scene functionalities in Harmony via SSL, it may be necessary to
specify the root CA certificates and/or its intermediates, as Harmony may nototherw ise be able to recognize the authority of the CA w ho signed yourcertificate.
Typically, you can obtain the root CA certificates or intermediate certificates fromthe root certificate authority of the certificate authority w ho signed your domain
certificate.

NOTE
If necessary, you can allow Harmony to trust the W ebCC server even if it
has a self-signed certificate—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

219

Chapter 3: W ebCC

About SSL, HTTPS and W ebCC on W indows
You can configure your W ebCC server to accept connections through the https protocol, either exclusively or
alongside the http protocol. Connections through https are encrypted and the identity of the server is verified
using a certificate. This ensures the information exchanged betw een the client and the server cannot be
deciphered if intercepted. Also, provided that you configure W ebCC w ith a certificate signed by a reputable
certificate authority, this ensures that hackers cannot perform man-in-the-middle attacks by making their ow nserver pose as your W ebCC server to intercept its traffic.
For W ebCC to accept connections w ith the https protocol, you must configure W ebCC w ith the follow ing:l

The port used for https connections.

l

The private certificate key.

l

The certificate.

l

Optionally, the root CA and/or intermediate certificate.

There are tw o types of certificates supported by W ebCC:
lPrivacy Enhanced Mail (PEM) certificates: These certificates are ASCII files encoded in Base64.
Typically, the certificate is in a file w ith a .crt, .cer or .pem extension and the private key is in a file
w ith a .key extension.

lPersonal Information Exchange (PFX /PKCS #12) certificates: These certificates are binary files that
include both the certificate and its private key. Typically, such certificates are used for W indow s servers
and have a .pfx or .p12 extension.

If your certificate is in any other format, such as DER, PKCS #7 or CA_bundle, you w ill need to perform extra
steps to convert the certificate to a supported format.

About Certificate Signature
It is recommended to use a certificate that has been signed by a reputable certificate authority.
If your certificate is signed by a certificate authority, W ebCC w ill typically be accessible w ithout issue in a w eb
brow ser. How ever, if you w ant clients to be able to upload and dow nload scene changes directly betw een
Harmony and the W ebCC server, you may have to specify the root and/or intermediate certificate for yourcertificate. This is because w eb brow sers are typically designed to trace a certificate's chain of trust all the w ay
to the root certificate authority, w hereas Harmony is not.
If your certificate is self-signed, w eb brow sers w ill w arn the user that the w ebsite is not secure, and users w illneed to go around that w arning to access W ebCC. Likew ise, Harmony w ill not be able to upload or dow nload
scene changes directly from its interface at all, unless the client makes Harmony trust self-signed certificatesby enabling the hidden preference WEBCC_SSL_SELF_SIGNED—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

220

Harmony 22 Installation Guide

Configuring W ebCC to Use SSL on W indows
Like other W ebCC options, configuring W ebCC to use SSL is done by using command line parameters w hen
launching W ebCC. To use W ebCC w ith SSL, you must specify the -https parameter follow ed by the port
W ebCC should use for https connections, the certificate and key file.
The follow ing are examples of parameters to use for configuring W ebCC to use SSL:l

If you have a PEM certificate and key file:-https 8443 -key <path to PEM key file> -cert <path to PEM certificate>l

If you have a PEM certificate and its private key in the same file, specify the same file using both the key and -cert parameters:-https 8443 -key <path to PEM certificate> -cert <path to PEM certificate>l

If you have a PFX certificate, simply specify its path w ith the -pfx parameter:-https 8443 -pfx <path to PFX certificate>l

If you w ant to allow users to connect to your server via either http or https, you can do so by specifying
a port number for each protocol:-http 8080 -https 8443 -key <path to key file> -cert <path to certificate>l

If you have a root certificate, an intermediate certificate, or both, you can specify each file preceded by
the -ca parameter, in any order:-http 8443 -key <path to key file> -cert <path to certificate> -ca <path to intermediate certif

How to stop the W ebCC server service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.

221

Chapter 3: W ebCC

3. In the Process Starter drop-dow n, select HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on the Command Line field and press the End key to move the text cursor after webcc.bat.
6. After webcc.bat, add a space, then type each parameter you w ant to add, separated by spaces.
For example, if you w ant W ebCC to use the port number 8081, you w ould edit the line like so:
C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22 [Edition]\win64\bin\webcc.bat

NOTE
For a list of parameters and their usage, see HTTPS/SSL Parameters Table on page223.

7. Click on Update parameters to save the command line parameters.
8. Click on Start to restart W ebCC.

How to add parameters for W ebCC in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. If you w ant to let any user connect to W ebCC w ithout credentials and have administrative
privileges, uncheck the Authentication option. Otherw ise, make sure it is checked.
5. If you w ant to change the port used by the W ebCC server, type the desired port number in the Port
field.
6. If you w ant to specify any other option, type them in the Other Parameters field, separated by
spaces.

222

Harmony 22 Installation Guide

NOTE
For a list of parameters and their usage, see HTTPS/SSL Parameters Table on page223.

7. In the top menu, select Server > Save All Settings.
8. Click on the Stop button.
9. Click on the Launch button.

HTTPS/SSL Parameters Table
The follow ing parameters can be used to enable and configure SSL for your W ebCC server.
Parameter

Description

Enables connection to the server through the https protocol using the specified
port number.

-https <port number>

A commonly used port for accessing W ebCC through the https protocol is 8443.
For w eb brow sers to access W ebCC via https w ithout specifying the port
number—provided that the address of the server is preceded by https://—youcan use port 443.
For https to w ork, you must either specify a pair of PEM format key and certificate
w ith the -key and -cert option, or a PFX format certificate w ith the -pfx
option.

If access through the https protocol is enabled, this parameter allow s you to also
allow access through the http protocol through the specified port.

-http <port number>

Using this parameter is optional. If the -https parameter is specified, but not the-http parameter, W ebCC w ill only accept connections through https.
The default port for accessing W ebCC through the http protocol is 8080. Forbrow sers to access W ebCC via http w ithout specifying the port number, you can
use port 80.

The location of the private key file for the SSL session. This must be specified
along w ith the -cert parameter.
-key <key file>

The private key must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the key is encoded in Base64 and located betw een -----BEGIN
PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private
keys in this format have a .key extension.

223

Chapter 3: W ebCC

Parameter

Description

The location of the security certificate file for the SSL session. This must be
specified along w ith the -key parameter.
-cert <certificate
file>-pfx <pfx certificate
file>

The certificate must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the certificate is encoded in Base64 and located betw een ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
Typically, such certificates have a .crt, .cer or .pem extension.

If you have a Personal Information Exchange (PFX) certificate, you can use thisparameter to specify its location, instead of using a PEM certificate and key.
Typically, such certificates have a .pfx or .p12 extension. Since thesecertificates include their ow n private key, specifying a key w ith this certificate type
is not required.

If you have a domain certificate that is signed by a certificate authority (CA), thisparameter allow s you to specify the root CA certificate and/or its intermediate
certificates.
If you w ant to specify several certificates so as to compose the chain going fromyour domain certificate to the root CA certificate, you can repeat the parameter,like so:-ca <intermediate certificate 1> -ca <intermediate
certificate 2> -ca <root CA certificate>-ca <root ca
certificate file>

Typically, you w ill be able to log on to W ebCC using SSL from a W eb brow sereven if W ebCC is only configured w ith your domain certificate, provided that it issigned by a reputable certificate authority. How ever, if you w ant project
collaborators to be able to use the Download Database Changes and Update
Database Scene functionalities in Harmony via SSL, it may be necessary to
specify the root CA certificates and/or its intermediates, as Harmony may nototherw ise be able to recognize the authority of the CA w ho signed yourcertificate.
Typically, you can obtain the root CA certificates or intermediate certificates fromthe root certificate authority of the certificate authority w ho signed your domain
certificate.

NOTE
If necessary, you can allow Harmony to trust the W ebCC server even if it
has a self-signed certificate—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

224

Harmony 22 Installation Guide

Setting Up Static IPs for W ebCC on W indows
It is common to configure server machines to have a static IP. This avoids having to rely on DNS resolution tofind the server w hen its IP address changes, and it also allow s you to associate the hostname to the server's
static IP address on the machine to skip DNS resolution altogether, increasing netw ork performance.
If your machine is currently connected to a DHCP server that dynamically assigns IP addresses, you canconfigure your machine to permanently use its current IP address. To do this, you can start by making note of
the information for your current netw ork connection, then using these parameters for a permanent IP address.

How to obtain the information about your current connection
1. Open Command Prompt and enter the follow ing command:.
> ipconfig /allThis w ill output information about your current connection:
Windows IP Configuration
Host Name . . . . . . . . . . . . : <hostname>Primary Dns Suffix . . . . . . . : <domain name>
Node Type . . . . . . . . . . . . : Peer-Peer
IP Routing Enabled. . . . . . . . : No
WINS Proxy Enabled. . . . . . . . : No
DNS Suffix Search List. . . . . . : <domaine names>
Ethernet adapter Ethernet:
Connection-specific DNS Suffix . : <domain name>
Description . . . . . . . . . . . : <adapter name>
Physical Address. . . . . . . . . : <MAC address>
DHCP Enabled. . . . . . . . . . . : Yes
Autoconfiguration Enabled . . . . : Yes
Link-local IPv6 Address . . . . . : <IPv6 address>
IPv4 Address. . . . . . . . . . . : <IPv4 address>
Subnet Mask . . . . . . . . . . . : <subnet mask>
Lease Obtained. . . . . . . . . . : <date of lease>
Lease Expires . . . . . . . . . . : <date of expiration>
Default Gateway . . . . . . . . . : <default gateway>
DHCP Server . . . . . . . . . . . : <DHCP server address>
DHCPv6 IAID . . . . . . . . . . . : <DHCPv6 IAID>
DHCPv6 Client DUID. . . . . . . . : <DHCPv6 Client DUID>
DNS Servers . . . . . . . . . . . : <DNS server addresses>
Primary WINS Server . . . . . . . : <WINS server address>
NetBIOS over Tcpip. . . . . . . . : Enabled225

Chapter 3: W ebCC

2. In the output, under Ethernet adapter Ethernet, make note of the follow ing data:l

The domains in the DNS Suffix Search Listl

The IPv4 Addressl

The Subnet Maskl

The Default Gateway addressl

The addresses for the DNS Servers

How to configure a W indows server to use a static IP
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. Click View network status and tasks.
3. On the top-left corner of the Netw ork and Sharing Center, select Change adapter settings.

4. Right-click on the netw ork adapter used by your machine to connect to your local netw ork, thenselect Properties.

226

Harmony 22 Installation Guide

The Local Area Connection Properties dialog appears.

5. In the items list, select Internet Protocol Version 4 (TCP/IPv4).
6. Click on the Properties button under the list.
The Internet Protocol Version 4 (TCP/IPv4) Properties dialog box opens.

7. Select the Use the following IP address option.
8. In the IP Address field, enter the IPv4 Address you obtained in earlier.

227

Chapter 3: W ebCC

9. In the Subnet mask field, enter the Subnet mask you obtained earlier.
10. In the Default gateway field, enter the Default gateway address you obtained earlier.
11. Select the Use the following DNS server addresses option.
12. In the Preferred DNS server field, enter the DNS Servers address obtained earlier.
13. If a second DNS server w as listed by ipconfig, type it in the Alternate DNS server field. Otherw ise,leave this field empty.
14. Click on Advanced.
The Advanced TCP/IP Settings dialog opens.
15. Select the DNS tab.

16. Select the Append these DNS suffixes (in order): option.
17. For each DNS Suffix obtained earlier, click on Add, then type in the suffix. Add the suffixes in theorder in w hich there w ere listed.
18. Click on OK.
19. Click on OK in the Internet Protocol Version 4 (TCP/IPv4) Properties dialog.
20. Click on OK in the Ethernet Properties dialog.

228

Harmony 22 Installation Guide

Opening the Firewall Ports for a Harmony W ebCC Server on W indows
By default, the W indow s firew all w ill block the communication betw een client w orkstations attempting toconnect to the Harmony server and the database server service. In order to allow clients to connect to yourserver, you must open the ports used by the database server on the server machine.

How to open the ports for the W ebCC server on W indows
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. Click on System and Security.
3. Click on W indows Defender Firewall.
4. Click on Advanced settings.
The W indow s Defender Firew all w ith Advanced Security w indow opens.
5. In the list to the left, select Inbound Rules.
6. In the Actions list to the right, select New Rule.
The New Inbound Rule W izard appears.
7. Under W hat type of rule would you like to create?, select Port and click on Next.
8. Under Does this rule apply to TCP or UDP?, select TCP.
9. Under Does this rule apply to all local ports or specific local ports?, select Specify local ports.
10. In the text field, type the port number 8080.

NOTE
8080 is the default port used by the W ebCC server. You can customize this port
number—see Configuring W ebCC w ith Custom Parameters on W indow s on page 215.

11. Click on Next.
12. Under W hat action should be taken [...], select Allow the connection and click on Next.
13. Under W hen does this rule apply?, check the netw ork types over w hich clients w ill attempt toconnect to this server, then click on Next.

229

Chapter 3: W ebCC

14. In the name field, name the rule "Toon Boom W ebCC Server".
15. Click on Finish.
Clients on your netw ork w ill now be able to connect to the W ebCC server.

NOTE
If your W ebCC server is configured to allow both http and https connections, you w ill need to
add a firew all rule for the port used by both protocols.

230Harmony 22 Installation Guide

Checking the W ebCC Server Log on W indows
In order to troubleshoot problems w ith a W ebCC erver, you can look through its log. This is done differently
depending on w hether you installed the database server as a W indow s service using Configuration W izard or
using Service Launcher.

How to check the log for the W ebCC server service
1. Open an Explorer w indow .
2. Brow se to the follow ing location:
C:\ProgramData\Toon Boom Animation\Toon Boom Harmony
3. Right-click on WebControlCenter.log and select Open with > Notepad.

How to check the log for the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

231

Chapter 3: W ebCC

Launching the W ebCC Server Manually on W indows
You can start the W ebCC server directly from a command line. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems. You can view the output of the server
directly in the command line as it launches and handles requests.

How to start the W ebCC server manually
1. In a command line, enter the follow ing command:> C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\win64\bin\webcc.bat

232Harmony 22 Installation Guide

Stopping and Restarting the W ebCC Server on W indows
If you installed the W ebCC server as a W indow s service using Configuration W izard, you can stop it andrestart it using the Harmony Control Panel or the W indow s Services control panel. If you installed it using
Service Launcher, you can stop it and restart it manually in Service Launcher.

How to stop the W ebCC server service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. W hen you are ready to start the server again, click on Start.

How to stop the W ebCC server service using the W indows Services control panel
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, navigate to System and Security > Administrative Tools.
3. Double-click on Services.
4. Scroll-dow n to HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

233

Chapter 3: W ebCC

5. Right-click on the service and select Stop.
6. W hen you are ready to start the server again, right-click on it and select Start.

How to stop and restart the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

234

Harmony 22 Installation Guide

Uninstalling the W ebCC Server on W indows
If you installed the W ebCC server as a W indow s service using Configuration W izard, you can uninstall it using
the Configuration W izard, the Harmony Control Panel or the W indow s Services control panel. If you installed
it using Service Launcher, you can uninstall it in Service Launcher.

How to uninstall the W ebCC service using Configuration W izard
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
3. In the list of tasks, right of Harmony W eb Control Center Server, click on ....
4. In the ensuing dialog, under Do you wish to install the Harmony W eb Control Center Server?,select No.
5. Click on Next.
6. Click on Finish to confirm the changes.
The W ebCC server service w ill stop and w ill no longer launch on boot.

How to uninstall the W ebCC server service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on Remove.
The W ebCC server service w ill stop and w ill no longer launch on boot.
6. Close the Control Panel.

235

Chapter 3: W ebCC

How to uninstall the W ebCC server service using the W indows Services control panel
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, navigate to System and Security > Administrative Tools.
3. Double-click on Services.
4. Scroll-dow n to HarmonyStarter0- webcc.bat.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

5. Double-click on the service to open its Properties dialog.
6. In the Startup type drop-dow n, select Disabled.
From that point on, the W ebCC server service w ill no longer launch on boot.
7. Click on OK.

How to uninstall the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

236

Harmony 22 Installation Guide

Installing W ebCC on macOSOn W indow s, installing a W ebCC server w ith the default parameters can easily be done using theConfiguration Assistant.
Installing the W ebCC Server Daemon on macOS

238

Running the W ebCC Server on Log- In on macOS

240

Configuring W ebCC with Custom Parameters on macOS

242

About SSL, HTTPS and W ebCC on macOS

247

Configuring W ebCC for SSL Support on macOS

248

Configuring a macOS W ebCC Server to have a Static IP Address

252

Looking Up the W ebCCServer Log on macOS255

Launching the W ebCC Server Manually on macOS256

Stopping and Restarting the W ebCC Server on macOS

257

Uninstalling the W ebCC Server on macOS

258

237

Chapter 3: W ebCC

Installing the W ebCC Server Daemon on macOSYou can easily install W ebCC as a daemon using the Configuration W izard. This daemon runs through theuser usabatch, so this user must be created prior to installing the daemon.

NOTE
The follow ing steps indicate how to make the W ebCC server daemon launch on boot, via the user
usabatch, w ho w ill have administrator privileges. If you prefer, you can make the database serverlaunch on log-in as the logged-in user. For more information, see Running the Database Server on
Log-In on macOS on page 83.

How to create the user usabatch on macOS
1. Open the Apple menu and select System Preferences.
2. Click on Users and Groups.
3. In the bottom-left corner of the Users & Groups dialog, click on the lock icon labeled Click the lockto make changes to get administrator permissions.
4. Enter the username and passw ord of an account w ith administrator privileges.
5. Click on the + button at the bottom of the user list.
The user creation panel appears.
6. In the New Account drop-dow n, select Administrator.
7. In the Full Name and Account Name fields, enter usabatch.
8. Give the user a passw ord.
9. Click on Create User.

How to install the W ebCC server daemon on macOS
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
1. In the W elcome screen, check the Create the Startup Items option and uncheck all other options.
2. Click on Continue.

238

Harmony 22 Installation Guide

3. Check the Create Harmony W eb Control Center Server Startup Item option and uncheck allother options.
4. Click on Create.
5. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
The W ebCC daemon is now installed and should be running. You can test that it w orks bylaunching a w eb brow ser and going to the follow ing address:
http://localhost:8080/

239

Chapter 3: W ebCC

Running the W ebCC Server on Log- In on macOSThe traditional w ay of running a W ebCC server is by running the server as a daemon. This means it launches
and allow s clients to connect as soon as the machine is booted, w ithout any user being signed-in.
Using Service Launcher, it is possible to configure your W ebCC server to only launch as the currently loggedin user, w hen they log in. This means that W ebCC w ill only be accessible if the user configured to run it islogged in.
Although this may seem impractical, it may be preferable for security reasons. Services installed w ith theConfiguration W izard are run under the user usabatch, an user w ith administrator privileges w hich is createdby Configuration W izard to launch the services. W hen using Service Launcher, the logged-in user does notneed to have administrator privileges to run services.
Before configuring Service Launcher to run the W ebCC server, the daemon that launches it must be disabled,so as to avoid launching tw o instances of the W ebCC server simultaneously

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the W ebCC server daemon
1. In a terminal, type in the follow ing command:$ sudo launchctl unload/Library/LaunchDaemons/com.toonboom.WebCCServer.plist
The W ebCC server daemon w ill stop and w ill no longer launch on boot.

How to configure the W ebCC server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

240Harmony 22 Installation Guide

2. Do one of the follow ing:l

If Service Launcher is not running, follow these steps to launch it:a. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] anddouble-click Harmony [Edition].
The main Harmony application launches.
b. In the top menu, select Harmony [Edition] > Tools > Service Launcher.
l

If Service Launcher is already running, click on its iconin the menu bar.

The Service Launcher application w indow appears.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the W ebCC tab.
5. Check the Launch when Service Launcher starts option.
6. To make sure users must enter their passw ord w hen logging in to W ebCC, check the
Authentication option.
7. By default, W ebCC w ill use port 8080. If you w ant to use a specific port to connect to W ebCC, type
it in the Port field.
8. Click on Launch to verify that W ebCC launches successfully through Service Launcher using theselected parameters.
9. In the top menu, select Server > Save All Settings.
From now on, the database server w ill launch through Service Launcher w hen you log in

NOTE
You can enter parameters in the Other Parameters field to customize the W ebCC server. For
more information, see Configuring W ebCC w ith Custom Parameters on macOS on page 242.

241

Chapter 3: W ebCC

Configuring W ebCC with Custom Parameters on macOSW ebCC can run w ith no parameters, but it also provides some customization options. Among other things, you
can change the port number, adjust its security settings and configure it to run w ith SSL security.
If you installed W ebCC as a daemon, you can customize its parameters by modifying the daemon
configuration file that launches W ebCC. If you use Service Launcher to run W ebCC, you can easily add
parameters in the Other Parameters field of the W ebCC tab of Service Launcher.

How to add parameters to the W ebCC daemon
1. In a terminal, type in the follow ing command to edit the W ebCC daemon:$ sudo vi /Library/LaunchDaemons/com.toonboom.WebCCServer.plist
2. Scroll all the w ay dow n to the follow ing line:<string>export PATH="$USADIR/macosx/bin:$PATH"; "$USADIR/macosx/bin/webcc.sh" </string>

3. Right after "$USADIR/macosx/bin/webcc.sh", add a space, then type each parameter you
w ant to add, separated by spaces. For example, if you w ant W ebCC to use the port number 8081,
you w ould edit the line like so:<string>export PATH="$USADIR/macosx/bin:$PATH"; "$USADIR/macosx/bin/webcc.sh" -port 8081</striNOTE
For a list of parameters and their usage, see W ebCC Parameters Table on page 243.

4. Save and quit.
5. Restart the W ebCC daemon:$ sudo launchctl load
/Library/LaunchDaemons/com.toonboom.WebCCServer.plist

How to add parameters for W ebCC in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher
The Service Launcher application opens.

242

icon.

Harmony 22 Installation Guide

3. Double-click on Service Launcher.
The Service Launcher application launches.
4. Select the W ebCC tab.
5. If you w ant to let any user connect to W ebCC w ithout credentials and have administrative
privileges, uncheck the Authentication option. Otherw ise, make sure it is checked.
6. If you w ant to change the port used by the W ebCC server, type the desired port number in the Port
field.
7. If you w ant to specify any other option, type them in the Other Parameters field, separated by
spaces.

NOTE
For a list of parameters and their usage, see W ebCC Parameters Table on page 243.

8. In the top menu, select Server > Save All Settings.
9. Click on the Stop button.
10. Click on the Launch button.

W ebCC Parameters Table
The follow ing is a table of parameters that can be specified to customize the behaviour of your W ebCC server.
They can be used in both the W ebCC shell script and in Service Launcher.
Parameter

Description-numWorkers <number>

The amount of server nodes to launch to process client requests. Each noderequires one CPU core, and a single node can only process one client request at atime. Therefore, the more nodes are launched, the less likely the server is to stallunder heavy load.
If this parameter is not specified, W ebCC w ill use as many nodes as there are
CPU cores on the server.

-noAuthDisables authentication. W ith this option enabled, any user accessing the W ebCC
w eb interface w ill be logged in as usabatch and w ill administrative privileges on
the entire database.

The port to w hich W ebCC is deployed.
-port <port number>
The default port for accessing W ebCC is 8080. For brow sers to access W ebCC

243

Chapter 3: W ebCC

Parameter

Description

w ithout specifying the port number, you can use port 80.

NOTE
If either the -http or -https parameter is specified, the -port parameterw ill be ignored.

-exchange<directory>

The location of the exchange directory on the local filesystem. This directory is
w here all packages are stored w hen exporting or importing scenes.
By default, this directory is /USA_DB/exchange.

-cacheDuration<seconds>

The amount of seconds to keep data in the cache. This can be set to any value
betw een 1 and 999999. By default, this is set to 3600.

Enables cross-origin resource sharing on the W ebCC server.

-allowAllOrigin

By default, as a standard security measure, only files on the same server as theW ebCC server are allow ed to use W ebCC resources. W ith this option enabled, it
is possible to create w eb interfaces on other servers that use resources stored on
the W ebCC server, or to store different modules of W ebCC on different servers
and let them communicate together.
In most use cases, this option should be disabled to prevent other machines from
exploiting resources on the W ebCC server.

-disableAnalytics

Disables Google Analytics tracking for all clients. By default, this is enabled.

Overrides a default permission for the given user type.
-permission <usertype> <action><on|off>

At the moment, this parameter can only be used for the user type animator andfor the permission import_export_any_scene. Hence, w hen used w ith thefollow ing syntax, animator-type users can export and import any scene in the
database, w ithout requiring the scene to be assigned to them first.
-permission animator import_export_any_scene on

HTTPS/SSL Parameters Table
The follow ing parameters can be used to enable and configure SSL for your W ebCC server.

244

Harmony 22 Installation Guide

NOTE
For more information on how to configure W ebCC w ith SSL, see About SSL, HTTPS and W ebCC
on macOS on page 247.

Parameter

Description

Enables connection to the server through the https protocol using the specified
port number.

-https <port number>

A commonly used port for accessing W ebCC through the https protocol is 8443.
For w eb brow sers to access W ebCC via https w ithout specifying the port
number—provided that the address of the server is preceded by https://—youcan use port 443.
For https to w ork, you must either specify a pair of PEM format key and certificate
w ith the -key and -cert option, or a PFX format certificate w ith the -pfx
option.

If access through the https protocol is enabled, this parameter allow s you to also
allow access through the http protocol through the specified port.

-http <port number>

Using this parameter is optional. If the -https parameter is specified, but not the-http parameter, W ebCC w ill only accept connections through https.
The default port for accessing W ebCC through the http protocol is 8080. Forbrow sers to access W ebCC via http w ithout specifying the port number, you can
use port 80.

The location of the private key file for the SSL session. This must be specified
along w ith the -cert parameter.
-key <key file>

The private key must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the key is encoded in Base64 and located betw een -----BEGIN
PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private
keys in this format have a .key extension.

The location of the security certificate file for the SSL session. This must be
specified along w ith the -key parameter.
-cert <certificate
file>

The certificate must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the certificate is encoded in Base64 and located betw een ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
Typically, such certificates have a .crt, .cer or .pem extension.

-pfx <pfx certificate
file>

If you have a Personal Information Exchange (PFX) certificate, you can use thisparameter to specify its location, instead of using a PEM certificate and key.

245

Chapter 3: W ebCC

Parameter

Description

Typically, such certificates have a .pfx or .p12 extension. Since thesecertificates include their ow n private key, specifying a key w ith this certificate type
is not required.

If you have a domain certificate that is signed by a certificate authority (CA), thisparameter allow s you to specify the root CA certificate and/or its intermediate
certificates.
If you w ant to specify several certificates so as to compose the chain going fromyour domain certificate to the root CA certificate, you can repeat the parameter,like so:-ca <intermediate certificate 1> -ca <intermediate
certificate 2> -ca <root CA certificate>-ca <root ca
certificate file>

Typically, you w ill be able to log on to W ebCC using SSL from a W eb brow sereven if W ebCC is only configured w ith your domain certificate, provided that it issigned by a reputable certificate authority. How ever, if you w ant project
collaborators to be able to use the Download Database Changes and Update
Database Scene functionalities in Harmony via SSL, it may be necessary to
specify the root CA certificates and/or its intermediates, as Harmony may nototherw ise be able to recognize the authority of the CA w ho signed yourcertificate.
Typically, you can obtain the root CA certificates or intermediate certificates fromthe root certificate authority of the certificate authority w ho signed your domain
certificate.

NOTE
If necessary, you can allow Harmony to trust the W ebCC server even if it
has a self-signed certificate—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

246

Harmony 22 Installation Guide

About SSL, HTTPS and W ebCC on macOSYou can configure your W ebCC server to accept connections through the https protocol, either exclusively or
alongside the http protocol. Connections through https are encrypted and the identity of the server is verified
using a certificate. This ensures the information exchanged betw een the client and the server cannot be
deciphered if intercepted. Also, provided that you configure W ebCC w ith a certificate signed by a reputable
certificate authority, this ensures that hackers cannot perform man-in-the-middle attacks by making their ow nserver pose as your W ebCC server to intercept its traffic.
For W ebCC to accept connections w ith the https protocol, you must configure W ebCC w ith the follow ing:l

The port used for https connections.

l

The private certificate key.

l

The certificate.

l

Optionally, the root CA and/or intermediate certificate.

There are tw o types of certificates supported by W ebCC:
lPrivacy Enhanced Mail (PEM) certificates: These certificates are ASCII files encoded in Base64.
Typically, the certificate is in a file w ith a .crt, .cer or .pem extension and the private key is in a file
w ith a .key extension.

lPersonal Information Exchange (PFX /PKCS #12) certificates: These certificates are binary files that
include both the certificate and its private key. Typically, such certificates are used for W indow s servers
and have a .pfx or .p12 extension.

If your certificate is in any other format, such as DER, PKCS #7 or CA_bundle, you w ill need to perform extra
steps to convert the certificate to a supported format.

About Certificate Signature
It is recommended to use a certificate that has been signed by a reputable certificate authority.
If your certificate is signed by a certificate authority, W ebCC w ill typically be accessible w ithout issue in a w eb
brow ser. How ever, if you w ant clients to be able to upload and dow nload scene changes directly betw een
Harmony and the W ebCC server, you may have to specify the root and/or intermediate certificate for yourcertificate. This is because w eb brow sers are typically designed to trace a certificate's chain of trust all the w ay
to the root certificate authority, w hereas Harmony is not.
If your certificate is self-signed, w eb brow sers w ill w arn the user that the w ebsite is not secure, and users w illneed to go around that w arning to access W ebCC. Likew ise, Harmony w ill not be able to upload or dow nload
scene changes directly from its interface at all, unless the client makes Harmony trust self-signed certificatesby enabling the hidden preference WEBCC_SSL_SELF_SIGNED—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

247

Chapter 3: W ebCC

Configuring W ebCC for SSL Support on macOS
Like other W ebCC options, configuring W ebCC to use SSL is done by using command line parameters w hen
launching W ebCC. To use W ebCC w ith SSL, you must specify the -https parameter follow ed by the port
W ebCC should use for https connections, the certificate and key file.
The follow ing are examples of parameters to use for configuring W ebCC to use SSL:l

If you have a PEM certificate and key file:-https 8443 -key <path to PEM key file> -cert <path to PEM certificate>l

If you have a PEM certificate and its private key in the same file, specify the same file using both the key and -cert parameters:-https 8443 -key <path to PEM certificate> -cert <path to PEM certificate>l

If you have a PFX certificate, simply specify its path w ith the -pfx parameter:-https 8443 -pfx <path to PFX certificate>l

If you w ant to allow users to connect to your server via either http or https, you can do so by specifying
a port number for each protocol:-http 8080 -https 8443 -key <path to key file> -cert <path to certificate>l

If you have a root certificate, an intermediate certificate, or both, you can specify each file preceded by
the -ca parameter, in any order:-http 8443 -key <path to key file> -cert <path to certificate> -ca <path to intermediate certif

How to add parameters to the W ebCC daemon
1. In a terminal, type in the follow ing command to edit the W ebCC daemon:$ sudo vi /Library/LaunchDaemons/com.toonboom.WebCCServer.plist
2. Scroll all the w ay dow n to the follow ing line:<string>export PATH="$USADIR/macosx/bin:$PATH"; "$USADIR/macosx/bin/webcc.sh" </string>248

Harmony 22 Installation Guide

3. Right after "$USADIR/macosx/bin/webcc.sh", add a space, then type each parameter you
w ant to add, separated by spaces. For example, if you w ant W ebCC to use the port number 8081,
you w ould edit the line like so:<string>export PATH="$USADIR/macosx/bin:$PATH"; "$USADIR/macosx/bin/webcc.sh" -port 8081</striNOTE
For a list of parameters and their usage, see HTTPS/SSL Parameters Table on page250.

4. Save and quit.
5. Restart the W ebCC daemon:$ sudo launchctl load
/Library/LaunchDaemons/com.toonboom.WebCCServer.plist

How to add parameters for W ebCC in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Double-click on Service Launcher.
The Service Launcher application launches.
4. Select the W ebCC tab.
5. If you w ant to let any user connect to W ebCC w ithout credentials and have administrative
privileges, uncheck the Authentication option. Otherw ise, make sure it is checked.
6. If you w ant to change the port used by the W ebCC server, type the desired port number in the Port
field.
7. If you w ant to specify any other option, type them in the Other Parameters field, separated by
spaces.

NOTE
For a list of parameters and their usage, see HTTPS/SSL Parameters Table on page
250.

249

Chapter 3: W ebCC

8. In the top menu, select Server > Save All Settings.
9. Click on the Stop button.
10. Click on the Launch button.

HTTPS/SSL Parameters Table
The follow ing parameters can be used to enable and configure SSL for your W ebCC server.
Parameter

Description

Enables connection to the server through the https protocol using the specified
port number.

-https <port number>

A commonly used port for accessing W ebCC through the https protocol is 8443.
For w eb brow sers to access W ebCC via https w ithout specifying the port
number—provided that the address of the server is preceded by https://—youcan use port 443.
For https to w ork, you must either specify a pair of PEM format key and certificate
w ith the -key and -cert option, or a PFX format certificate w ith the -pfx
option.

If access through the https protocol is enabled, this parameter allow s you to also
allow access through the http protocol through the specified port.

-http <port number>

Using this parameter is optional. If the -https parameter is specified, but not the-http parameter, W ebCC w ill only accept connections through https.
The default port for accessing W ebCC through the http protocol is 8080. Forbrow sers to access W ebCC via http w ithout specifying the port number, you can
use port 80.

The location of the private key file for the SSL session. This must be specified
along w ith the -cert parameter.
-key <key file>

The private key must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the key is encoded in Base64 and located betw een -----BEGIN
PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private
keys in this format have a .key extension.

The location of the security certificate file for the SSL session. This must be
specified along w ith the -key parameter.
-cert <certificate
file>

The certificate must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the certificate is encoded in Base64 and located betw een ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.

250

Harmony 22 Installation Guide

Parameter

Description

Typically, such certificates have a .crt, .cer or .pem extension.

-pfx <pfx certificate
file>

If you have a Personal Information Exchange (PFX) certificate, you can use thisparameter to specify its location, instead of using a PEM certificate and key.
Typically, such certificates have a .pfx or .p12 extension. Since thesecertificates include their ow n private key, specifying a key w ith this certificate type
is not required.

If you have a domain certificate that is signed by a certificate authority (CA), thisparameter allow s you to specify the root CA certificate and/or its intermediate
certificates.
If you w ant to specify several certificates so as to compose the chain going fromyour domain certificate to the root CA certificate, you can repeat the parameter,like so:-ca <intermediate certificate 1> -ca <intermediate
certificate 2> -ca <root CA certificate>-ca <root ca
certificate file>

Typically, you w ill be able to log on to W ebCC using SSL from a W eb brow sereven if W ebCC is only configured w ith your domain certificate, provided that it issigned by a reputable certificate authority. How ever, if you w ant project
collaborators to be able to use the Download Database Changes and Update
Database Scene functionalities in Harmony via SSL, it may be necessary to
specify the root CA certificates and/or its intermediates, as Harmony may nototherw ise be able to recognize the authority of the CA w ho signed yourcertificate.
Typically, you can obtain the root CA certificates or intermediate certificates fromthe root certificate authority of the certificate authority w ho signed your domain
certificate.

NOTE
If necessary, you can allow Harmony to trust the W ebCC server even if it
has a self-signed certificate—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

251

Chapter 3: W ebCC

Configuring a macOS W ebCC Server to have a Static IP Address
It is common to configure server machines to have a static IP. This avoids having to rely on DNS resolution tofind the server w hen its IP address changes, and it also allow s you to associate the hostname to the server's
static IP address on the machine to skip DNS resolution altogether, increasing netw ork performance.
If your machine is currently connected to a DHCP server that dynamically assigns IP addresses, you canconfigure your machine to permanently use its current IP address. To do this, you can start by making note of
the information for your current netw ork connection, then using these parameters for a permanent IP address.

How to obtain information about your current connection on macOS
1. Open the Apple menu and select System Preferences.
2. Click on Network.
The Netw ork configuration panel appears.

3. In the list to the left, select Ethernet.
4. In the panel to the right, make note of the follow ing information:l

The IP Addressl

The Subnet Maskl

The Router addressl

The DNS Serverl

The Search Domains

252Harmony 22 Installation Guide

How to configure a macOS server to use a static IP
1. Open the Apple menu and select System Preferences.
2. Click on Network.
3. In the list to the left, select Ethernet.
4. In the Location drop-dow n, select Edit Locations.

5. Click on the + button to add a location, then name it Static.

6. Click on Done.

253

Chapter 3: W ebCC

7. Click on Advanced.
8. In the TCP/IP tab of the Advanced Netw ork panel, enter the follow ing information:l

Set the IPv4 Address to the IP Address obtained earlier.

l

Set the Subnet Mask to the Subnet Mask obtained earlier.

l

Set the Router address to the Router address obtained earlier.

9. Open the DNS tab.
10. Under the DNS Servers list, click on the + button to add a DNS server. Add each of the DNS Server
addresses obtained earlier.
11. Under the Search Domains list, click on the + button to add a search domain. Add each of thesearch domains obtained earlier.
12. Click on OK.
If your configuration w orks, the Netw ork panel w ill indicate Status: Connected at the top.

254

Harmony 22 Installation Guide

Looking Up the W ebCCServer Log on macOS
In order to troubleshoot problems w ith a W ebCC server, you can look through its log. This is done differently
depending on w hether you installed the database server as a daemon using Configuration Assistant, or using
Service Launcher.

How to check the log for the W ebCC server daemon
1. In a terminal, enter the follow ing command:$ less /tmp/com.toonboom.WebCCServer.log

How to check the log for the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

255

Chapter 3: W ebCC

Launching the W ebCC Server Manually on macOSYou can start the W ebCC server directly from a terminal. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems. You can view the output of the server
directly in the command line as it launches and handles requests.

How to start the W ebCC server manually
1. In a command line, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/webcc.sh"256

Harmony 22 Installation Guide

Stopping and Restarting the W ebCC Server on macOSIf you installed the W ebCC server as a daemon using the Configuration Assistant, you can stop it and restart itusing the launchctl command line tool. If you installed it using Service Launcher, you can stop it and restart
it manually in Service Launcher.

How to stop and restart the W ebCC server daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload/Library/LaunchDaemons/com.toonboom.WebCCServer.plist
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo launchctl load
/Library/LaunchDaemons/com.toonboom.WebCCServer.plist

How to stop and restart the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

257

Chapter 3: W ebCC

Uninstalling the W ebCC Server on macOSIf you installed the W ebCC server as a daemon using the Configuraton Assistant, you can uninstall it using thelaunchctl command line tool. If you installed it using Service Launcher, you can uninstall it in Service
Launcher.

How to uninstall the W ebCC server daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload -w/Library/LaunchDaemons/com.toonboom.WebCCServer.plist
The daemon w ill no longer launch on boot.
2. If you w ant, you can delete the daemon permanently w ith the follow ing command:$ sudo rm /Library/LaunchDaemons/com.toonboom.WebCCServer.plist

How to uninstall the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

258

Harmony 22 Installation Guide

Installing W ebCC on GNU/LinuxOn W indow s, installing a W ebCC server w ith the default parameters can easily be done using the Harmony
installation script.
Disabling Security for a W ebCC Server on GNU/Linux

260

Installing W ebCC on GNU/Linux

262

Running the W ebCC Server on Log- In on GNU/Linux264

Configuring W ebCC with Custom Parameters on GNU/Linux

266

About SSL, HTTPS and W ebCC on GNU/Linux

271

Configuring W ebCC for SSL Support on GNU/Linux

272

Setting Up Static IPs for W ebCC on GNU/Linux

276

Opening the Firewall Ports for a W ebCC Server on GNU/Linux280

Checking the W ebCC Server Log on GNU/Linux281

Launching the W ebCC Server Manually on GNU/Linux

282

Stopping and Restarting the W ebCC Server on GNU/Linux

283

Uninstalling the W ebCC Server on GNU/Linux

284

259

Chapter 3: W ebCC

Disabling Security for a W ebCC Server on GNU/Linux
GNU/Linux comes bundled w ith tw o core security components:l

A firew all (typically either iptables or firewalld), w hich w ill block incoming connections that w ere notspecifically allow ed.

l

SELinux, a kernel security module that enforces access control policies on softw are, files and netw ork
resources.

The default configuration for these components w ill prevent clients from connecting to a W ebCC server. Thisinstallation guide provides instructions on how to add security exceptions to these components so that they do
not have to be disabled. How ever, you may prefer to disable them so as to simplify the installation process or
to rule out security components as possible causes w hen troubleshooting an issue.

IMPORTANT
If you choose to disable security on GNU/Linux, it is critical to ensure that your domain has
effective site-w ide security mechanisms to prevent unauthorized access to your W ebCC server.

How to disable the firewall on CentOS 6, RedHat Entreprise Linux 6 or other systems
using the iptables service
1. In a terminal, enter the follow ing commands:$ sudo chkconfig iptables off$ sudo service iptables stop

How to disable the firewall on CentOS 7, RedHat Entreprise Linux 7 or other systems
using the firewalld service
1. In a terminal, enter the follow ing commands:$ sudo systemctl disable firewalld$ sudo systemctl stop firewalld

How to disable SELinux
1. In a terminal, enter the follow ing command:$ sudo vi /etc/selinux/config
2. Find the line w ith the follow ing parameter:

260

Harmony 22 Installation Guide

SELINUX=enforcing

3. Replace enforcing w ith disabled:
SELINUX=disabled

IMPORTANT
Double-check to make sure you did not make any typo. An error in the SELinuxconfiguration file may cause GNU/Linux to fail to boot.

4. Save and quit.
5. Reboot to apply the new configuration.

261

Chapter 3: W ebCC

Installing W ebCC on GNU/LinuxThe Harmony installer for GNU/Linux alw ays installs daemon scripts on your machine, but does not enable
them by default. Hence, there are tw o approaches to installing the W ebCC server daemon:l

By enabling the daemon that w as already installed w ith Harmony using the chkconfig command.

l

By running the Harmony installation script w ith the -w parameter.

The installation of a W ebCC server also requires copying a script from the Harmony installation package. The
installer does this automatically w hen it is launched w ith the -w parameter. If you choose to enable theW ebCC daemon manually, you w ill also have to copy this script manually.
This daemon runs through the user usabatch, so this user must be created prior to installing the daemon.

NOTE
The follow ing steps indicate how to make the W ebCC server daemon launch on boot, via the user
usabatch. If you prefer, you can make the database server launch on log-in as the logged-in user.
For more information, see Running the Database Server on Log-In on macOS on page 83.

How to create the usabatch user on GNU/Linux
1. In a terminal, enter the follow ing command:$ sudo useradd -m usabatch$ sudo passwd usabatch
2. W hen prompted, enter the passw ord you w ant to assign to the user usabatch, then confirm it.
The user usabatch is now created and can be used to run Harmony daemons.

How to enable the W ebCC server daemon on GNU/Linux
1. In a terminal, enter the follow ing command to check if the rendering script for W ebCC is already inyour database:$ stat /USA_DB/scripts/TB_WebCC_Render.js
2. If the script is not in your database, copy it from the Harmony installation directory:$ mkdir -p -m 777 /USA_DB/scripts$ cp /usr/local/ToonBoomAnimation/harmony[Edition]_
22/resources/scripts/TB_WebCC_Render.js /USA_DB/scripts/
3. In a terminal, enter the follow ing command to enable the W ebCC server daemon:$ sudo chkconfig toonboom_webcc on

262

Harmony 22 Installation Guide

If the command returns nothing, it succeeded. The W ebCC server w ill launch next time you bootthe machine.
4. To launch the W ebCC server daemon immediately, run the follow ing command:$ sudo service toonboom_webcc start
The command w ill report w hether it succeeded or failed.

How to enable the W ebCC server daemon using the Harmony installation script
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package
4. Run the installer w ith the -d parameter:$ sudo ./install -w
5. W hen prompted, confirm that you w ant to proceed w ith the installation.
The installation script w ill enable and start the W ebCC server daemon.

263

Chapter 3: W ebCC

Running the W ebCC Server on Log- In on GNU/LinuxThe traditional w ay of running a W ebCC server is by running the server as a daemon. This means it launches
and allow s clients to connect as soon as the machine is booted, w ithout any user being signed-in.
Using Service Launcher, it is possible to configure your W ebCC server to only launch as the currently loggedin user, w hen they log in. This means that W ebCC w ill only be accessible if the user configured to run it islogged in.
Although this may seem impractical, it may be preferable for security reasons. Services installed w ith theConfiguration W izard are run under the user usabatch, an user w ith administrator privileges w hich is createdby Configuration W izard to launch the services. W hen using Service Launcher, the logged-in user does notneed to have administrator privileges to run services.
Before configuring Service Launcher to run the W ebCC server, the daemon that launches it must be disabled,so as to avoid launching tw o instances of the W ebCC server simultaneously

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the W ebCC server daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_webcc stop$ sudo chkconfig toonboom_webcc off
The W ebCC server daemon w ill stop and w ill no longer launch on boot.

How to configure the W ebCC server to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

264Harmony 22 Installation Guide

2. Do one of the follow ing:l

If Service Launcher is not running, in the GNOME top menu, select Applications > Harmony
22 [Edition] >lService Launcher.

If Service Launcher is already running, click on its iconin the system tray.

The Service Launcher application starts.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the W ebCC tab.
5. Check the Launch when Service Launcher starts option.
6. To make sure users must enter their passw ord w hen logging in to W ebCC, check the
Authentication option.
7. By default, W ebCC w ill use port 8080. If you w ant to use a specific port to connect to W ebCC, type
it in the Port field.
8. Click on Launch to verify that W ebCC launches successfully through Service Launcher using theselected parameters.
9. In the top menu, select Server > Save All Settings.
From now on, the W ebCC server w ill launch through Service Launcher w hen you log in.

NOTE
You can enter parameters in the Other Parameters field to customize the W ebCC server. For
more information, see Configuring W ebCC w ith Custom Parameters on GNU/Linux on page
266

265

Chapter 3: W ebCC

Configuring W ebCC with Custom Parameters on GNU/LinuxW ebCC can run w ith no parameters, but it also provides some customization options. Among other things, you
can change the port number, adjust its security settings and configure it to run w ith SSL security.
If you installed W ebCC as a daemon, you can customize its parameters by modifying the shell script thatlaunches W ebCC, w hich the daemon launches. If you use Service Launcher to run W ebCC, you can easily add
parameters in the Other Parameters field of the W ebCC tab of Service Launcher.

How to edit the W ebCC shell script and add parameters
1. In a terminal, type in the follow ing command:$ sudo vi /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/webcc.sh
2. Scroll all the w ay dow n to the follow ing line:./bin_3rdParty/node ../../cloud/server/app.js "$@"

3. Right after app.js, add a space, then type each parameter you w ant to add, separated by spaces.
For example, if you w ant W ebCC to use the port number 8081, you w ould edit the line like so:./bin_3rdParty/node ../../cloud/server/app.js -port 8081 "$@"NOTE
For a list of parameters and their usage, see W ebCC Parameters Table on page 267.

4. Save and quit.
5. For your changes to take effect, restart the service w ith the follow ing command:$ sudo service toonboom_webcc restart

How to add parameters for W ebCC in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher
The Service Launcher application opens.

266

icon.

Harmony 22 Installation Guide

3. Select the W ebCC tab.
4. If you w ant to let any user connect to W ebCC w ithout credentials and have administrative
privileges, uncheck the Authentication option. Otherw ise, make sure it is checked.
5. If you w ant to change the port used by the W ebCC server, type the desired port number in the Port
field.
6. If you w ant to specify any other option, type them in the Other Parameters field, separated by
spaces.

NOTE
For a list of parameters and their usage, see W ebCC Parameters Table on page 267.

7. In the top menu, select Server > Save All Settings.
8. Click on the Stop button.
9. Click on the Launch button.

W ebCC Parameters Table
The follow ing is a table of parameters that can be specified to customize the behaviour of your W ebCC server.
They can be used in both the W ebCC shell script and in Service Launcher.
Parameter

Description-numWorkers <number>

The amount of server nodes to launch to process client requests. Each noderequires one CPU core, and a single node can only process one client request at atime. Therefore, the more nodes are launched, the less likely the server is to stallunder heavy load.
If this parameter is not specified, W ebCC w ill use as many nodes as there are
CPU cores on the server.

-noAuthDisables authentication. W ith this option enabled, any user accessing the W ebCC
w eb interface w ill be logged in as usabatch and w ill administrative privileges on
the entire database.

The port to w hich W ebCC is deployed.
-port <port number>

The default port for accessing W ebCC is 8080. For brow sers to access W ebCC
w ithout specifying the port number, you can use port 80.

267

Chapter 3: W ebCC

Parameter

Description

NOTE
If either the -http or -https parameter is specified, the -port parameterw ill be ignored.

-exchange<directory>

The location of the exchange directory on the local filesystem. This directory is
w here all packages are stored w hen exporting or importing scenes.
By default, this directory is /USA_DB/exchange.

-cacheDuration<seconds>

The amount of seconds to keep data in the cache. This can be set to any value
betw een 1 and 999999. By default, this is set to 3600.

Enables cross-origin resource sharing on the W ebCC server.

-allowAllOrigin

By default, as a standard security measure, only files on the same server as theW ebCC server are allow ed to use W ebCC resources. W ith this option enabled, it
is possible to create w eb interfaces on other servers that use resources stored on
the W ebCC server, or to store different modules of W ebCC on different servers
and let them communicate together.
In most use cases, this option should be disabled to prevent other machines from
exploiting resources on the W ebCC server.

-disableAnalytics

Disables Google Analytics tracking for all clients. By default, this is enabled.

Overrides a default permission for the given user type.
-permission <usertype> <action><on|off>

At the moment, this parameter can only be used for the user type animator andfor the permission import_export_any_scene. Hence, w hen used w ith thefollow ing syntax, animator-type users can export and import any scene in the
database, w ithout requiring the scene to be assigned to them first.
-permission animator import_export_any_scene on

HTTPS/SSL Parameters Table
The follow ing parameters can be used to enable and configure SSL for your W ebCC server.

NOTE
For more information on how to configure W ebCC w ith SSL, see About SSL, HTTPS and W ebCC
on GNU/Linux on page 271.

268

Harmony 22 Installation Guide

Parameter

Description

Enables connection to the server through the https protocol using the specified
port number.

-https <port number>

A commonly used port for accessing W ebCC through the https protocol is 8443.
For w eb brow sers to access W ebCC via https w ithout specifying the port
number—provided that the address of the server is preceded by https://—youcan use port 443.
For https to w ork, you must either specify a pair of PEM format key and certificate
w ith the -key and -cert option, or a PFX format certificate w ith the -pfx
option.

If access through the https protocol is enabled, this parameter allow s you to also
allow access through the http protocol through the specified port.

-http <port number>

Using this parameter is optional. If the -https parameter is specified, but not the-http parameter, W ebCC w ill only accept connections through https.
The default port for accessing W ebCC through the http protocol is 8080. Forbrow sers to access W ebCC via http w ithout specifying the port number, you can
use port 80.

The location of the private key file for the SSL session. This must be specified
along w ith the -cert parameter.
-key <key file>

The private key must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the key is encoded in Base64 and located betw een -----BEGIN
PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private
keys in this format have a .key extension.

The location of the security certificate file for the SSL session. This must be
specified along w ith the -key parameter.
-cert <certificate
file>

The certificate must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the certificate is encoded in Base64 and located betw een ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
Typically, such certificates have a .crt, .cer or .pem extension.

-pfx <pfx certificate
file>

If you have a Personal Information Exchange (PFX) certificate, you can use thisparameter to specify its location, instead of using a PEM certificate and key.
Typically, such certificates have a .pfx or .p12 extension. Since thesecertificates include their ow n private key, specifying a key w ith this certificate type
is not required.

-ca <root ca
certificate file>If you have a domain certificate that is signed by a certificate authority (CA), thisparameter allow s you to specify the root CA certificate and/or its intermediate269

Chapter 3: W ebCC

Parameter

Description

certificates.
If you w ant to specify several certificates so as to compose the chain going fromyour domain certificate to the root CA certificate, you can repeat the parameter,like so:-ca <intermediate certificate 1> -ca <intermediate
certificate 2> -ca <root CA certificate>
Typically, you w ill be able to log on to W ebCC using SSL from a W eb brow sereven if W ebCC is only configured w ith your domain certificate, provided that it issigned by a reputable certificate authority. How ever, if you w ant project
collaborators to be able to use the Download Database Changes and Update
Database Scene functionalities in Harmony via SSL, it may be necessary to
specify the root CA certificates and/or its intermediates, as Harmony may nototherw ise be able to recognize the authority of the CA w ho signed yourcertificate.
Typically, you can obtain the root CA certificates or intermediate certificates fromthe root certificate authority of the certificate authority w ho signed your domain
certificate.

NOTE
If necessary, you can allow Harmony to trust the W ebCC server even if it
has a self-signed certificate—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

270

Harmony 22 Installation Guide

About SSL, HTTPS and W ebCC on GNU/LinuxYou can configure your W ebCC server to accept connections through the https protocol, either exclusively or
alongside the http protocol. Connections through https are encrypted and the identity of the server is verified
using a certificate. This ensures the information exchanged betw een the client and the server cannot be
deciphered if intercepted. Also, provided that you configure W ebCC w ith a certificate signed by a reputable
certificate authority, this ensures that hackers cannot perform man-in-the-middle attacks by making their ow nserver pose as your W ebCC server to intercept its traffic.
For W ebCC to accept connections w ith the https protocol, you must configure W ebCC w ith the follow ing:l

The port used for https connections.

l

The private certificate key.

l

The certificate.

l

Optionally, the root CA and/or intermediate certificate.

There are tw o types of certificates supported by W ebCC:
lPrivacy Enhanced Mail (PEM) certificates: These certificates are ASCII files encoded in Base64.
Typically, the certificate is in a file w ith a .crt, .cer or .pem extension and the private key is in a file
w ith a .key extension.

lPersonal Information Exchange (PFX /PKCS #12) certificates: These certificates are binary files that
include both the certificate and its private key. Typically, such certificates are used for W indow s servers
and have a .pfx or .p12 extension.

If your certificate is in any other format, such as DER, PKCS #7 or CA_bundle, you w ill need to perform extra
steps to convert the certificate to a supported format.

About Certificate Signature
It is recommended to use a certificate that has been signed by a reputable certificate authority.
If your certificate is signed by a certificate authority, W ebCC w ill typically be accessible w ithout issue in a w eb
brow ser. How ever, if you w ant clients to be able to upload and dow nload scene changes directly betw een
Harmony and the W ebCC server, you may have to specify the root and/or intermediate certificate for yourcertificate. This is because w eb brow sers are typically designed to trace a certificate's chain of trust all the w ay
to the root certificate authority, w hereas Harmony is not.
If your certificate is self-signed, w eb brow sers w ill w arn the user that the w ebsite is not secure, and users w illneed to go around that w arning to access W ebCC. Likew ise, Harmony w ill not be able to upload or dow nload
scene changes directly from its interface at all, unless the client makes Harmony trust self-signed certificatesby enabling the hidden preference WEBCC_SSL_SELF_SIGNED—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

271

Chapter 3: W ebCC

Configuring W ebCC for SSL Support on GNU/Linux
Like other W ebCC options, configuring W ebCC to use SSL is done by using command line parameters w hen
launching W ebCC. To use W ebCC w ith SSL, you must specify the -https parameter follow ed by the port
W ebCC should use for https connections, the certificate and key file.
The follow ing are examples of parameters to use for configuring W ebCC to use SSL:l

If you have a PEM certificate and key file:-https 8443 -key <path to PEM key file> -cert <path to PEM certificate>l

If you have a PEM certificate and its private key in the same file, specify the same file using both the key and -cert parameters:-https 8443 -key <path to PEM certificate> -cert <path to PEM certificate>l

If you have a PFX certificate, simply specify its path w ith the -pfx parameter:-https 8443 -pfx <path to PFX certificate>l

If you w ant to allow users to connect to your server via either http or https, you can do so by specifying
a port number for each protocol:-http 8080 -https 8443 -key <path to key file> -cert <path to certificate>l

If you have a root certificate, an intermediate certificate, or both, you can specify each file preceded by
the -ca parameter, in any order:-http 8443 -key <path to key file> -cert <path to certificate> -ca <path to intermediate certif

How to edit the W ebCC shell script and add parameters
1. In a terminal, type in the follow ing command:$ sudo vi /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/webcc.sh
2. Scroll all the w ay dow n to the follow ing line:./bin_3rdParty/node ../../cloud/server/app.js "$@"

272

Harmony 22 Installation Guide

3. Right after app.js, add a space, then type each parameter you w ant to add, separated by spaces.
For example, if you w ant W ebCC to use the port number 8081, you w ould edit the line like so:./bin_3rdParty/node ../../cloud/server/app.js -port 8081 "$@"NOTE
For a list of parameters and their usage, see HTTPS/SSL Parameters Table on page274.

4. Save and quit.
5. For your changes to take effect, restart the service w ith the follow ing command:$ sudo service toonboom_webcc restart

How to add parameters for W ebCC in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. If you w ant to let any user connect to W ebCC w ithout credentials and have administrative
privileges, uncheck the Authentication option. Otherw ise, make sure it is checked.
5. If you w ant to change the port used by the W ebCC server, type the desired port number in the Port
field.
6. If you w ant to specify any other option, type them in the Other Parameters field, separated by
spaces.

NOTE
For a list of parameters and their usage, see HTTPS/SSL Parameters Table on page274.

7. In the top menu, select Server > Save All Settings.
8. Click on the Stop button.
9. Click on the Launch button.

273

Chapter 3: W ebCC

HTTPS/SSL Parameters Table
The follow ing parameters can be used to enable and configure SSL for your W ebCC server.
Parameter

Description

Enables connection to the server through the https protocol using the specified
port number.
A commonly used port for accessing W ebCC through the https protocol is 8443.
For w eb brow sers to access W ebCC via https w ithout specifying the port
-https <port number>number—provided that the address of the server is preceded by https://—youcan use port 443.
For https to w ork, you must either specify a pair of PEM format key and certificate
w ith the -key and -cert option, or a PFX format certificate w ith the -pfx
option.

If access through the https protocol is enabled, this parameter allow s you to also
allow access through the http protocol through the specified port.

-http <port number>

Using this parameter is optional. If the -https parameter is specified, but not the-http parameter, W ebCC w ill only accept connections through https.
The default port for accessing W ebCC through the http protocol is 8080. Forbrow sers to access W ebCC via http w ithout specifying the port number, you can
use port 80.

The location of the private key file for the SSL session. This must be specified
along w ith the -cert parameter.
-key <key file>

The private key must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the key is encoded in Base64 and located betw een -----BEGIN
PRVATE KEY----- and -----END PRIVATE KEY----- tags. Typically private
keys in this format have a .key extension.

The location of the security certificate file for the SSL session. This must be
specified along w ith the -key parameter.
-cert <certificate
file>-pfx <pfx certificate
file>

The certificate must be in Privacy Enhanced Mail (PEM) format, w hich is an ASCII
format w here the certificate is encoded in Base64 and located betw een ----BEGIN CERTIFICATE----- and -----END CERTIFICATE----- tags.
Typically, such certificates have a .crt, .cer or .pem extension.

If you have a Personal Information Exchange (PFX) certificate, you can use thisparameter to specify its location, instead of using a PEM certificate and key.
Typically, such certificates have a .pfx or .p12 extension. Since thesecertificates include their ow n private key, specifying a key w ith this certificate type274

Harmony 22 Installation Guide

Parameter

Description

is not required.

If you have a domain certificate that is signed by a certificate authority (CA), thisparameter allow s you to specify the root CA certificate and/or its intermediate
certificates.
If you w ant to specify several certificates so as to compose the chain going fromyour domain certificate to the root CA certificate, you can repeat the parameter,like so:-ca <intermediate certificate 1> -ca <intermediate
certificate 2> -ca <root CA certificate>-ca <root ca
certificate file>

Typically, you w ill be able to log on to W ebCC using SSL from a W eb brow sereven if W ebCC is only configured w ith your domain certificate, provided that it issigned by a reputable certificate authority. How ever, if you w ant project
collaborators to be able to use the Download Database Changes and Update
Database Scene functionalities in Harmony via SSL, it may be necessary to
specify the root CA certificates and/or its intermediates, as Harmony may nototherw ise be able to recognize the authority of the CA w ho signed yourcertificate.
Typically, you can obtain the root CA certificates or intermediate certificates fromthe root certificate authority of the certificate authority w ho signed your domain
certificate.

NOTE
If necessary, you can allow Harmony to trust the W ebCC server even if it
has a self-signed certificate—see Disabling SSL Certificate Validation for
W ebCC in Harmony on page 293.

275

Chapter 3: W ebCC

Setting Up Static IPs for W ebCC on GNU/LinuxIt is common to configure server machines to have a static IP. This avoids having to rely on DNS resolution tofind the server w hen its IP address changes, and it also allow s you to associate the hostname to the server's
static IP address on the machine to skip DNS resolution altogether, increasing netw ork performance.
If your machine is currently connected to a DHCP server that dynamically assigns IP addresses, you canconfigure your machine to permanently use its current IP address. To do this, you can start by making note of
the information for your current netw ork connection, then using these parameters for a permanent IP address.

How to obtain your current network configuration on CentOS 6
1. To obtain your machine's hostname, enter the follow ing command:$ hostname
W rite dow n the output value.
2. To obtain the netw ork domain, enter the follow ing command:$ hostname -d
W rite dow n the output value.
3. To obtain your machine's default gatew ay and netw ork device, enter the follow ing command:$ routeThe output w ill look like this:Destination
10.120.0.0
default

Gateway*<default gateway>

Genmask<subnet mask>
0.0.0.0

Flags Metric Ref
U
1
0
UG
0
0

Use Iface
0 <device name>0 <device name>One of the row s w ill have default in the destination column. In this row , the name of the device in
the Iface column is the name of your default netw ork device. W rite dow n the name of that device.
4. To obtain your machine's IP and subnet mask, enter the follow ing command, replacing <device
name> w ith the name of the device noted in the previous step:$ nmcli -f all dev list iface <device name>
Information about the netw ork interface w ill appear, in either one of the follow ing formats:
GENERAL.DEVICE:
GENERAL.TYPE:
GENERAL.DRIVER:
GENERAL.HWADDR:
GENERAL.STATE:CAPABILITIES.CARRIER-DETECT:CAPABILITIES.SPEED:<device name>802-3-ethernet
tg3<MAC address>
connected
yes1000 Mb/s

276

Harmony 22 Installation Guide

WIRED-PROPERTIES.CARRIER:
IP4-SETTINGS.ADDRESS:
IP4-SETTINGS.PREFIX:
IP4-SETTINGS.GATEWAY:
IP4-DNS1.DNS:on<IPv4 address><prefix> (<subnet mask>)<default gateway><DNS server address>

W rite dow n the IPv4 address, the subnet mask, the default gatew ay as w ell as every DNS server
address listed.

NOTE
You can also obtain the IP address (inet addr) and netw ork mask (Mask) of your device w ith
the command:$ ifconfig <device name>How to obtain your current network configuration on CentOS 7
1. To obtain your machine's hostname, enter the follow ing command:$ hostname
W rite dow n the output value.
2. To obtain the netw ork domain, enter the follow ing command:$ hostname -d
W rite dow n the output value.
3. To obtain your machine's default gatew ay and netw ork device, enter the follow ing command:$ routeThe output w ill look like this:Destination
10.120.0.0
default

Gateway*<default gateway>

Genmask<subnet mask>
0.0.0.0

Flags Metric Ref
U
1
0
UG
0
0

Use Iface
0 <device name>0 <device name>One of the row s w ill have default in the destination column. In this row , the name of the device in
the Iface column is the name of your default netw ork device. W rite dow n the name of that device.
4. To obtain your machine's IP and subnet mask, enter the follow ing command, replacing <device
name> w ith the name of the device noted in the previous step:$ nmcli -p -f IP4 connection show <device name>
Information about the netw ork interface w ill appear. The output w ill be in this format.

277

Chapter 3: W ebCC===============================================================================
Activate connection details (0568a4c4-092a-46e9-9f25-2295a1389d6e)===============================================================================
IP4.ADDRESS[1]:<IPv4 address>/<prefix>
IP4.GATEWAY:<default gateway>
IP4.DNS[1]:<DNS server address>
IP4.DOMAIN[1]:<search domains>

W rite dow n the IPv4 address, the default gatew ay address, the DNS server address(es) and thesearch domain(s).
To obtain your subnet mask, enter the follow ing command, replacing <device name> w ith thename of the device noted in the previous step:$ nmcli -p -f DHCP4 connection show <device name> | grep 'subnet_mask'
The output should look like this:subnet_mask = <subnet mask>

DHCP4.OPTION[3]:W rite dow n the subnet mask.

NOTE
You can also obtain the IP address (inet) and netw ork mask (netmask) of your device w ith
the command:$ ifconfig <device name>How to set up a static IP for CentOS 6 and 7
1. Before you do this, make sure you have the follow ing information for your machine:lName of default netw ork device (ie: eth0, p3p1)lHostnamelDomain namelSearch domain(s)lIPv4 addresslNetw ork mask

278

Harmony 22 Installation Guidel

Default gatew ay addressl

DNS server address(es)2. Open your machine's netw ork configuration file for editing:$ sudo vi /etc/sysconfig/network
3. Configure the file as follow s, replacing the bolded text w ith the appropriate values:
NETWORKING=yes
HOSTNAME=<hostname>.<domain name>

4. Open your default netw ork interface's configuration file for editing. This file w ill be named ifcgfollow ed by the name of the netw ork interface you noted earlier. For example, if your netw ork
interface is named eth0, the configuration file w ill be named ifcfg-eth0:$ sudo vi /etc/sysconfig/network-scripts/ifcfg-<device name>
5. Configure the file w ith the appropriate values for the follow ing parameters. If a value is alreadydeclared for one of these parameters, replace it. If not, add it to the file:
DEVICE="<device name>"
BOOTPROTO=static
IPADDR=<IPv4 address>
NETMASK=<network mask>
GATEWAY=<default gateway>
ONBOOT=yes

6. Open the DNS configuration file for editing:$ sudo vi /etc/resolv.conf
7. Configure the file as follow s, replacing the bolded text w ith the appropriate values:
search <search domain mames>
nameserver <DNS server address>

NOTES
l

If you have several search domains, enter them all on the same line after search,separated by spaces.

l

If you have several DNS servers, add one nameserver line for each address.

8. Restart the netw ork service:$ sudo service network restart279

Chapter 3: W ebCC

Opening the Firewall Ports for a W ebCC Server on GNU/LinuxThe GNU/Linux firew all w ill block attempts from other computers to communicate w ith the W ebCC server. In
order to circumvent this, the ports used by the database server must be opened.

How to allow connections to the W ebCC server to go through the firewall on CentOS
6, RedHat Entreprise Linux 6 or other systems using the iptables service
1. Add the ports used by the W ebCC server to the list of open ports w ith the follow ing commands:$ sudo iptables -I INPUT -m state --state NEW -p tcp -m tcp --dport
8080 -j ACCEPT$ sudo service iptables save$ sudo service iptables restart
The GNU/Linux firew all should now allow other machines to connect to W ebCC.

NOTES
l

8080 is the default port used by the W ebCC server. You can customize this port number—see Configuring W ebCC w ith Custom Parameters on GNU/Linux on page 266.

l

If your W ebCC server is configured to allow both http and https connections, you w ill needto add a firew all rule for the port used by both protocols.

How to allow connections to the the W ebCC server to go through the firewall on
CentOS 7, RedHat Entreprise Linux 7 or other systems using the firewalld service
1. Add the ports used by the W ebCC server to the list of open ports w ith the follow ing commands:$ sudo firewall-cmd --permanent --zone=public --add-port=8080/tcp$ sudo firewall-cmd --reload
The GNU/Linux firew all should now allow other machines to connect to W ebCC.

NOTES
l

8080 is the default port used by the W ebCC server. You can customize this port number—see Configuring W ebCC w ith Custom Parameters on GNU/Linux on page 266.

l

If your W ebCC server is configured to allow both http and https connections, you w ill needto add a firew all rule for the port used by both protocols.

280Harmony 22 Installation Guide

Checking the W ebCC Server Log on GNU/Linux
In order to troubleshoot problems w ith a W ebCC server, you can look through its log. This is done differently
depending on w hether you installed the database server as a daemon or using Service Launcher.

How to check the log for the W ebCC server daemon
1. In a terminal, enter the follow ing command:$ less /tmp/webccserver.log

How to check the log for the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

281

Chapter 3: W ebCC

Launching the W ebCC Server Manually on GNU/LinuxYou can start the W ebCC server directly from a terminal. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems. You can view the output of the server
directly in the command line as it launches and handles requests.

How to start the W ebCC server manually
1. In a command line, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/webcc.sh282

Harmony 22 Installation Guide

Stopping and Restarting the W ebCC Server on GNU/LinuxIf you installed the W ebCC server as a daemon, you can stop it and restart it using the service command line
tool. If you installed it using Service Launcher, you can stop it and restart it manually in Service Launcher.

How to stop and restart the W ebCC server daemon
1. In a terminal, enter the follow ing command:$ sudo service toonboom_webcc stop
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo service toonboom_webcc start

TIP
You can also restart the service instantly w ith the follow ing command:$ sudo service toonboom_webcc restart

How to stop and restart the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

283

Chapter 3: W ebCC

Uninstalling the W ebCC Server on GNU/LinuxIf you installed the W ebCC server as a daemon, you can uninstall it using the chkconfig command line tool.
If you installed it using Service Launcher, you can uninstall it in Service Launcher.

How to disable the W ebCCserver daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_webcc stop$ sudo chkconfig toonboom_webcc off
The W ebCC server daemon w ill stop and w ill no longer launch on boot.

How to uninstall the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the W ebCC tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

284

Harmony 22 Installation Guide

Configuring Render Nodes for W ebCC Servers
In order to be able to generate small preview movies that can be played in a w eb brow ser for the scenes on
your Harmony database, the render nodes for your Harmony database must have the Cisco OpenH264 library
installed.
Because of copyright restrictions, this library is not installed automatically w ith Harmony. It must be
dow nloaded off the Cisco server as it is installed. How ever, regardless of the platform on w hich you areinstalling W ebCC, a configuration tool is provide to automate the procedure.

IMPORTANTl

The Cisco OpenH264 library must be installed on each machine on your database server's local
netw ork that w ill be configured to render scenes for your database.

lInstalling the Cisco OpenH264 library requires an Internet connection.

l

Further steps are required in order for a machine to be configured to render preview movies.
See Batch Processing.

Installing the Cisco OpenH264 Codec for W ebCC on W indows

286

Installing the Cisco OpenH264 Codec for W ebCC on macOS

287

Installing the Cisco OpenH264 Codec for W ebCC on GNU/Linux

288

285

Chapter 3: W ebCC

Installing the Cisco OpenH264 Codec for W ebCC on W indows
Batch processing machines must have the Cisco OpenH264 library installed in order to be able to generatesmall preview movies for W ebCC. Because of copyright restriction, this codec must be dow nloaded off Cisco's
servers as it is installed. The Configuration W izard can automatically dow nload it and copy it in Harmony's
installation directory.

NOTE
Installing the Cisco OpenH264 library requires a w orking Internet connection.

How to install the Cisco OpenH264 codec for W ebCC
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
3. In the list of tasks, right of Cisco OpenH264 Library, click on ....
4. In the ensuing dialog, under Do you wish to install the OpenH264 Library?, select Yes/Install.
5. Click on Next.
6. Click on Finish to confirm the changes.
The machine should now be able to generate preview movies for W ebCC.

IMPORTANTIn order to be able to generate preview movies for W ebCC, a machine must also be configured
to be a batch processing node for your database. For more information, see Batch Processing.

286

Harmony 22 Installation Guide

Installing the Cisco OpenH264 Codec for W ebCC on macOS
Batch processing machines must have the Cisco OpenH264 library installed in order to be able to generatesmall preview movies for W ebCC. Because of copyright restriction, this codec must be dow nloaded off Cisco's
servers as it is installed. The Configuration Assistant can automatically dow nload it and copy it in Harmony's
installation directory.

NOTE
Installing the Cisco OpenH264 library requires a w orking Internet connection.

How to install the Cisco OpenH264 codec for W ebCC
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
3. Check the Install/Uninstall Cisco OpenH264 Library option and uncheck all other options.
4. Under Choose to install or uninstall, select Install OpenH264 Library.
5. Click on Create.
6. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
The machine should now be able to generate preview movies for W ebCC.

IMPORTANTIn order to be able to generate preview movies for W ebCC, a machine must also be configured
to be a batch processing node for your database. For more information, see Batch Processing.

287

Chapter 3: W ebCC

Installing the Cisco OpenH264 Codec for W ebCC on GNU/Linux
Batch processing machines must have the Cisco OpenH264 library installed in order to be able to generatesmall preview movies for W ebCC. Because of copyright restriction, this codec must be dow nloaded off Cisco's
servers as it is installed.
There are tw o w ays to installing the Cisco OpenH264 library, both of w hich w ill automatically dow nload thelibrary and store it in the Harmony installation directory:l

By running the openh264_control.sh script packaged w ith Harmonyl

By running the Harmony installation script w ith the -openh264 parameter.

NOTE
Installing the Cisco OpenH264 library requires a w orking Internet connection.

How to install the Cisco OpenH264 codec for W ebCC using the script packaged with
Harmony
1. In a terminal, type in the follow ing commands:$ cd /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_64/bin$ sudo ./openh264_control.sh
2. W hen prompted, type i and press enter.
The machine should now be able to generate preview movies for W ebCC.

IMPORTANTIn order to be able to generate preview movies for W ebCC, a machine must also be configured
to be a batch processing node for your database. For more information, see Batch Processing.

How to enable the W ebCC server daemon using the Harmony installation script
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package

288

Harmony 22 Installation Guide

4. Run the installer w ith the -d parameter:$ sudo ./install -openh264
5. W hen prompted, confirm that you w ant to proceed w ith the installation.
The machine should now be able to generate preview movies for W ebCC.

IMPORTANTIn order to be able to generate preview movies for W ebCC, a machine must also be configured
to be a batch processing node for your database. For more information, see Batch Processing.

289

Chapter 3: W ebCC

Configuring Local W ebCC Clients
Since W ebCC is a w eb-based platform, the great majority of its functionalities are available to any computerthat has access to the W ebCC server through the w eb and has a compatible w eb brow ser.
How ever, w hile users w ho access the W ebCC server from a remote location must dow nload scenes so thatthey can w ork on them locally, users w ho access the W ebCC server from the same local netw ork as the
Harmony database server can open scenes directly from W ebCC into Harmony, w ithout dow nload them first.
To be able to this, the client machine must have Harmony Server installed and must be configured as aHarmony database client—see Connecting Client W orkstations to a Harmony Database Server on page 158.
On GNU/Linux the registration of the W ebCC URLs to open scenes in Harmony is not automatic. It must be
specifically enabled w hen installing Harmony.
Configuring a GNU/Linux W orkstation to Open Harmony Scenes from W ebCC

290

291

Harmony 22 Installation Guide

Configuring a GNU/Linux W orkstation to Open Harmony Scenes fromW ebCCThe GNU/Linux installer can configure your machine to open harmony:// URLs to open in Harmony. Such
URLs are used by W ebCC to open scenes directly in Harmony.

How to register the harmony:// URL handler on a GNU/Linux workstation
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package
4. Launch the installer w ith the -s parameter:$ sudo ./install -s
5. W hen prompted, confirm that you w ant to proceed w ith the installation.
The harmony:// URL handler is now registered to launch Harmony and open Harmony scenes.

NOTE
You may need to reboot the machine before this change takes effect.

291

Chapter 3: W ebCC

Configuring Remote W ebCC Clients
Since most of the functionalities of W ebCC are w eb-based, there is very little configuration to do on clientmachines. A machine that has access to the W ebCC server and has a compatible w eb brow ser can use all thew eb-based features of W ebCC, can dow nload scene packages.
How ever, w hen w orking on a scene exported from W ebCC in Harmony, it is possible to dow nload changes
made to the scene directly into the scene via Harmony. Likew ise, it is also possible to upload changes that you
made to the scene directly to the W ebCC server from Harmony.
In order to do this, you must configure Harmony to communicate w ith the W ebCC server. This is as simple as
typing in the full address of the server, as you do in your w eb brow ser.

NOTE
You w ill be prompted for your W ebCC username and passw ord w hen attempting to dow nloadchanges from W ebCC or to update a scene to W ebCC.

How to configure Harmony to communicate with W ebCC
1. In the top menu, select Edit (W indows/Linux) or Harmony [Edition] (macOS) > Preferences.
2. Open the General tab.
In the bottom-right corner of the tab, there should be a W eb Control Center section.

3. In the URL field of the W eb Control Center section, type in the URL of the W ebCC server including
the protocol, domain and port number, as you w ould in your w eb brow ser:
protocol://hostname:portnumber
For example, to access a server named webcc.mystudio through https via port 8843, you
w ould enter:
https://webccserver.mystudio:8843
4. Click on the OK button.

292

Harmony 22 Installation Guide

Disabling SSL Certificate Validation for W ebCC in Harmony
If your W ebCC server uses as self-signed certificate to support SSL, Harmony w ill not be able to dow nload
scene changes from the W ebCC server nor to upload scene changes to the W ebCC server. To w ork aroundthis, you can enable a hidden preferences that w ill allow Harmony to communicate w ith the W ebCC server
w ithout validating its SSL certificate.

IMPORTANT
If this option is enabled, Harmony w ill not be able to verify the identity of your W ebCC server
before it communicates w ith it, w hich may cause security vulnerabilities. This should only be done
for debugging purposes or if you are set on using a self-signed certificate for your W ebCC server.

How to disable SSL Certificate Validation in Harmony
1. Open the Script Editor view by doing one of the follow ing:l

In the top-right corner of an existing view (ie: the Camera or Draw ing view ), click on the Add
Viewlbutton and select Script Editor.

In the top menu, select W indows > Script Editor.

2. In the File list, select < < Sandbox > >.
3. In the script field, copy and paste the follow ing code:
preferences.setBool("WEBCC_SSL_SELF_SIGNED", true);

4. In the Script Editor toolbar, click on Run Script293.

Chapter 4: Batch Processing

Chapter 4: Batch Processing
Harmony Server allow s you to use batch processing to automatically delegate vectorization and renderingtasks to different computers, w hich w ill perform them in the background, so as to optimize your netw ork's
resources and avoid making project collaborators use their ow n w orkstation to render scenes, w hich can stall
their machine by using up all its resources during the process.
In other w ords, batch processing allow s you to create a render farm using the machines that are connected toyour Harmony database server.
There are tw o types of tasks performed by batch processing:

Vectorizing
Vectorization converts scanned draw ings to vector draw ings. Scanned draw ings are stored in bitmap format,
and must be converted to a vector-based format before they can be painted in Harmony. In a traditional
animation pipeline, this step is required before you can start painting scanned draw ings.
W hen scanning a draw ing using the Harmony [Edition] application, they are automatically sent to thevectorize queue of the database. It may sometimes be required to send draw ings for vectorization manually inControl Center, for example in the follow ing cases:l

To processing images that w ere not scanned in the Scan module.

l

To recover the unpainted draw ings after making an unrecoverable mistake w hile painting or postprocessing the scene.

l

To vectorize a pencil test.

You can open any specific job's vectorize queue in Control Center to check on the status of vectorization jobs.

Rendering
Also know n as compositing, rendering is the process of creating final frames for a scene and storing them as
image files as w ell as movie files. Rendered images have all their effects composited and are created in highquality, as they should be used for post-production and broadcasting.
Rendering a scene is a resource intensive process, and it is impractical for animators to use their ow n machines
to render their scenes after w orking on them, as the rendering process is likely to stall their machine andprevent them from w orking on their scene any further until it is completed. Hence, by setting up batchprocessing, they can delegate the rendering process by sending their scenes to the rendering queue. Machinesconfigured to perform batch processing w ill take care of performing the rendering job w hen they are ready andscheduled to do so.
You can open any specific job's render queue in Control Center to check on the status of rendering jobs.

Configuring Batch Processing
In order to configure batch processing for a Harmony database, machines that must perform batch processing
tasks must be configured to do so. This configuration procedure can be broken dow n in three basic steps:

294

Harmony 22 Installation Guide

1. Add the name of the machine that w ill perform batch processing to the Harmony database's machinelist.
2. Install the batch processing service on this machine. This service w ill run in the background and monitor
the database for batch processing tasks to perform, then process these tasks in the background.
3. Create a batch processing schedule for this machine. The machine must be on a batch processing
schedule in order to perform batch processing. Any single machine's schedule can be unrestricted,
w hich means the machine alw ays performs batch processing tasks if any are on queue, or can be
restricted to specific hours, specific environments and specific tasks. It is recommended to schedulemachines to perform renders outside of business hours so as to avoid impeding project collaborators bytaking up their machine's resources w hile they are w orking.

IMPORTANT
Configuring batch processing requires using command line tools frequently. It is highly
recommended to add the path to Harmony's command line tools to your machine's PATH
environment variable so that you do not have to type the full path to these command line tools in
the terminal.
To add Harmony to your path, follow the steps in the follow ing topics:l

Adding Harmony Executables to the %PATH% Environment Variable on W indow s on page 18lAdding Harmony Binaries to the $PATH Environment Variable on macOS on page 22lAdding Harmony Binaries to the $PATH Environment Variable on GNU/Linux on page 38

295

Chapter 4: Batch Processing

Creating machine- list Files
The machine-list file identifies all the machines on your netw ork that can be allow ed to batch process
Harmony scenes. The machines on this list represents your netw ork's render farm.

NOTE
You must have sufficient batch processing licenses to run batch processing on all the machines in
the machine-list file.

How to create the machine- list file
1. In a text editor, create a new file at this location/USA_DB/schedules/machine-list
2. In this text file, type in the hostname of every machine that you w ant to use for batch processing,one machine per line.
For example, you might have a machine-list, w here each line is the name of a computer on yournetw ork:anim-1anim-2anim-3
paint-1
paint-2
paint-3
layout-1
layout-2

NOTESl

There must be no blank lines in the machine-list file.

l

The order in w hich machines are listed determines their order in the batchprocessing scheduling commands.

l

You can obtain the name for a machine by typing hostname in a terminal orcommand prompt, regardless of the operating system.

3. Save the file.
The next time you use a scheduling command, it w ill be able to check up on or update the scheduleof any machine in the machine list file.

296

Harmony 22 Installation Guide

Batch Processing Installation
The main steps involved in installing batch processing creating the machine-list file and to install the batchprocessing service.

IMPORTANT
Make sure the Cisco OpenH264 codec is installed on all the machines that w ill do the batch renderof movie preview s—see Installing W ebCC on W indow s on page 210, Installing W ebCC on
macOS on page 237 and Installing W ebCC on GNU/Linux on page 259.

297

Chapter 4: Batch Processing

Installing the Batch Processing Service on W indows
On W indow s, you can install the batch processing service using the Configuration W izard to make it launch onboot as user usabatch, or Service Launcher to make it launch w hen the current user logs in.
Installing the Batch Processing Service on W indows

299

Running the Batch Processing Service on Log- In on W indows

300

Looking Up the Batch Processing Log on W indows

302

Launching Batch Processing Manually on W indows

303

Stopping and Restarting the Batch Processing Service on W indows

304

Interrupting a Batch Processing Task on W indows

306

Uninstalling the Batch Processing Service on W indows

307

298

Harmony 22 Installation Guide

Installing the Batch Processing Service on W indows
You can easily install batch processing as a W indow s service using the Configuration W izard. It w ill launch assoon as the machine boots, under user usabatch.

NOTE
The follow ing steps indicate how to make batch processing launch on boot, via the user usabatch,w ho w ill have administrator privileges. If you prefer, you can make the database server launch on
log-in as the logged-in user. For more information, see Running the Batch Processing Service on
Log-In on W indow s on page 300.

How to install the batch processing service
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
3. In the list of tasks, right of Batch Processing, click on ....
4. In the ensuing dialog, under W ill this computer perform batch processing?, select Yes.
5. Click on Next.
6. Under W hat is the name of the server?, type in the name of the database server.
7. Under W hat is the User?, type in the username
8. Click on Finish to confirm the changes.
The batch processing service is now installed and should be running. You can test that yourmachine is ready to perform batch processing job by entering the follow ing command in a terminal,
replacing <host name> w ith the name of your machine.
> Status -b -m <host name>299

Chapter 4: Batch Processing

Running the Batch Processing Service on Log- In on W indows
The traditional w ay of running the batch processing service is by running the server as a W indow s service or
daemon. This means the service launches in the background as soon as the machine boots, and starts
processing the queue even if nobody is logged in to the computer.
Using Service Launcher, it is possible to configure the batch processing service to launch as the currently
logged-in user, w hen they log in. This means that your machine w ill only process jobs w hen the user is logged
in.
Although this may seem impractical, it may be preferable for security reasons. Harmony services are run under
the user usabatch, an user w ith administrator privileges. W hen using Service Launcher, the logged-in user
does not need to have administrator privileges to run services.
Before configuring Service Launcher to run the batch processing service, the W indow s service that launches it
must be disabled, so as to avoid launching tw o instances of the batch processing service simultaneously.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the batch processing service on W indows
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- tbprocess - schedule.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on Remove.
From that point on, the batch processing service w ill no longer launch on boot.
6. Close the Control Panel.

300

Harmony 22 Installation Guide

How to configure the batch processing service to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

2. Do one of the follow ing:l

If Service Launcher is not running, open the Start menu and, in the Programs list, selectHarmony 22 [Edition] > Tools >lService Launcher.

If Service Launcher is already running, click on its iconin the notification tray.

The Service Launcher application launches.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the ToonBoom Process tab.
5. Make sure the Schedule option is checked.
6. Click on Launch to verify that the batch processing service launches successfully through Service
Launcher.
7. Check the Launch when Service Launcher starts option.
8. In the top menu, select Server > Save All Settings.
From now on, the batch processing service w ill launch through Service Launcher w hen you log in.
You can test that your machine is ready to perform batch processing job by entering the follow ing
command in a terminal, replacing <host name> w ith the name of your machine.
> Status -b -m <host name>301

Chapter 4: Batch Processing

Looking Up the Batch Processing Log on W indows
In order to troubleshoot problems w ith the batch processing service, you can look through its log. This is done
differently depending on w hether you installed batch processing as a W indow s service using Configuration
W izard or using Service Launcher.

How to check the log for the batch processing service
1. Open an Explorer w indow .
2. Brow se to the follow ing location:
C:\ProgramData\Toon Boom Animation\Toon Boom Harmony
3. Right-click on tbprocess.log and select Open with > Notepad.

How to check the log for the batch processing service in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

302

Harmony 22 Installation Guide

Launching Batch Processing Manually on W indows
You can start the batch processing service directly from a command prompt.This is usually not practical for a
production environment, but it can be very useful w hen troubleshooting problems. You can view the output of
the service directly in the terminal in w hich you launch it as it starts and handles jobs.

How to start the batch processing service manually
1. In a command prompt, enter the follow ing command:$ C:\Program Files (x86)\Toon Boom Animation\Toon Boom Harmony 22[Edition]\win64\bin\tbprocess -schedule303

Chapter 4: Batch Processing

Stopping and Restarting the Batch Processing Service on W indows
If you installed the batch processing service as a W indow s service using Configuration W izard, you can stop it
and restart it using the Harmony Control Panel or the W indow s Services control panel. If you installed it using
Service Launcher, you can stop it and restart it manually in Service Launcher.

How to stop the batch processing service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- tbprocess - schedule.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. W hen you are ready to start the server again, click on Start.

How to stop the batch processing service using the W indows Services control panel
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, navigate to System and Security > Administrative Tools.
3. Double-click on Services.
4. Scroll-dow n to HarmonyStarter0- tbprocess - schedule.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

304

Harmony 22 Installation Guide

5. Right-click on the service and select Stop.
6. W hen you are ready to start the server again, right-click on it and select Start.

How to stop and restart the batch processing service in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

305

Chapter 4: Batch Processing

Interrupting a Batch Processing Task on W indows
Control Center w ill allow you to cancel a batch processing task before it starts by deleting it from the queue,
but if you delete a batch processing task w hile it is already processing, it w ill still finish in the background.
Vectorizing tasks are added to the queue on a per-draw ing basis. This means that if you w ant to interrupt thevectorization of a scene, you can simply stop the batch processing service and clear the queue in Control
Center. How ever, rendering tasks are added to the queue on a per-scene basis. Therefore, the only w ay tointerrupt the rendering of a scene w hile it is currently rendering is by interrupting the Harmony process that isrendering the scene.

IMPORTANTYou should only interrupt a batch processing task w hen it is necessary, such as w hen an extremely
lengthy task w as started by accident and is liable to delay the other tasks.

How to interrupt a batch processing job
1. Press Ctrl + Alt + Del to open the W indow s security screen.
2. Select Task Manager.
3. If the Task Manager only lists the open applications and has no menu or tabs, select More details
at the bottom.
4. Open the Details tab.
5. Look for a process named tbprocess.exe.
6. Right-click on the process and select End process tree.
This w ill terminate the batch processing daemon (tbprocess.exe) as w ell as any Harmony
process it might have started to render a scene or vectorize draw ings. The batch processing
daemon should restart instantly, but it w ill not attempt to process the batch processing task thatw as interrupted again.

NOTE
The job you interrupted w ill still appear in the queue w ith the Processing status in Control
Center. You w ill need to delete the job manually from the queue to clear it up.

306

Harmony 22 Installation Guide

Uninstalling the Batch Processing Service on W indows
If you installed the batch processing service as a W indow s service using Configuration W izard, you canuninstall it using the Configuration W izard, the Harmony Control Panel or the W indow s Services control
panel. If you installed it using Service Launcher, you can uninstall it in Service Launcher.

How to uninstall the batch processing service using Configuration W izard
1. In the Start menu, open the Programs menu and select Harmony 22 [Edition] > Tools >Configuration W izard.
2. W hen prompted, enable Configuration W izard to make changes to your device.
The Toon Boom Harmony Configuration W izard launches.
3. In the list of tasks, right of Batch Processing, click on ....
4. In the ensuing dialog, under W ill this computer perform batch processing?, select No.
5. Click on Next.
6. Click on Finish to confirm the changes.
The batch processing service w ill stop and w ill no longer launch on boot.

How to uninstall the batch processing service using the Harmony Control Panel
1. Open the Start menu and, in the Programs menu, select Harmony 22 [Edition] > Tools >Control Panel.
2. W hen prompted, allow Control Panel to make changes to your device.
3. In the Process Starter drop-dow n, select HarmonyStarter0- tbprocess - schedule.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

4. Click on Stop.
5. Click on Remove.
The batch processing service w ill stop and w ill no longer launch on boot.
6. Close the Control Panel.

307

Chapter 4: Batch Processing

How to uninstall the W ebCC server service using the W indows Services control panel
1. Open the W indow s Control Panel:l

On W indows 7: Open the Start menu and select All Programs > Accessories > System
Tools > Control Panel.

l

On W indows 8.1 or W indows 10: Open the Start menu and, in the programs list, selectW indows System > Control Panel.

2. In the Control Panel, navigate to System and Security > Administrative Tools.
3. Double-click on Services.
4. Scroll-dow n to HarmonyStarter0- tbprocess - schedule.

NOTE
The number after HarmonyStarter may be different, depending on how many
Harmony services w ere installed before this one.

5. Double-click on the service to open its Properties dialog.
6. In the Startup type drop-dow n, select Disabled.
From that point on, the batch processing service w ill no longer launch on boot.
7. Click on OK.

How to uninstall the W ebCC server in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the notification tray, click on theService Launcher icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

308

Harmony 22 Installation Guide

Installing the Batch Processing Service on macOSOn macOS, you can install the batch processing service using the Configuration Assistant to make it launch onboot as user usabatch, or Service Launcher to make it launch w hen the current user logs in.
Installing the Batch Processing Daemon on macOS

310

Running the Batch Processing Service on Log- In on macOS

312

Looking Up the Batch Processing Log on macOS

314

Launching Batch Processing Manually on macOS315

Stopping and Restarting the Batch Processing Daemon on macOS

316

Interrupting a Batch Processing Task on macOS

317

Uninstalling the Batch Processing Daemon on macOS

319

309

Chapter 4: Batch Processing

Installing the Batch Processing Daemon on macOSOn macOS, you can install the batch processing daemon using the Configuration Assistant.

NOTE
The follow ing steps indicate how to make batch processing launch on boot, via the user usabatch,w ho w ill have administrator privileges. If you prefer, you can make the database server launch on
log-in as the logged-in user. For more information, see Running the Batch Processing Service on
Log-In on macOS on page 312.

How to create the user usabatch on macOS
1. Open the Apple menu and select System Preferences.
2. Click on Users and Groups.
3. In the bottom-left corner of the Users & Groups dialog, click on the lock icon labeled Click the lockto make changes to get administrator permissions.
4. Enter the username and passw ord of an account w ith administrator privileges.
5. Click on the + button at the bottom of the user list.
The user creation panel appears.
6. In the New Account drop-dow n, select Administrator.
7. In the Full Name and Account Name fields, enter usabatch.
8. Give the user a passw ord.
9. Click on Create User.

How to install the database server daemon on macOS
1. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] and double-click

Harmony [Edition].
The main Harmony application launches.
2. In the top menu, select Harmony [Edition] > Tools > Configuration Assistant.
1. In the W elcome screen, check the Create the Startup Items option and uncheck all other options.
2. Click on Continue.
3. Check the Create Queue Server Startup Item option and uncheck all other options.

310Harmony 22 Installation Guide

4. Click on Create.
5. W hen prompted, enter the username and the passw ord of a user w ith administrator privileges.
The batch processing daemon is now installed and should be running. You can test that yourmachine is ready to perform batch processing job by entering the follow ing command in a terminal,
replacing <host name> w ith the name of your machine.
$ Status -b -m <host name>311Chapter 4: Batch Processing

Running the Batch Processing Service on Log- In on macOSThe traditional w ay of running the batch processing service is by running the server as a W indow s service or
daemon. This means the service launches in the background as soon as the machine boots, and starts
processing the queue even if nobody is logged in to the computer.
Using Service Launcher, it is possible to configure the batch processing service to launch as the currently
logged-in user, w hen they log in. This means that your machine w ill only process jobs w hen the user is logged
in.
Although this may seem impractical, it may be preferable for security reasons. Harmony services are run under
the user usabatch, an user w ith administrator privileges. W hen using Service Launcher, the logged-in user
does not need to have administrator privileges to run services.
Before configuring Service Launcher to run the batch processing service, the w indow s service that launches it
must be disabled, so as to avoid launching tw o instances of the W ebCC server simultaneously.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the batch processing daemon on macOS
1. In a terminal, enter the follow ing command:$ sudo launchctl unload/Library/LaunchDaemons/com.toonboom.QueueServer.plist
The batch processing daemon w ill stop and w ill no longer launch on boot.

How to configure the batch processing daemon to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

312Harmony 22 Installation Guide

2. Do one of the follow ing:l

If Service Launcher is not running, follow these steps to launch it:a. In Finder, proceed to Applications >Toon Boom Harmony 22 [Edition] anddouble-click Harmony [Edition].
The main Harmony application launches.
b. In the top menu, select Harmony [Edition] > Tools > Service Launcher.
l

If Service Launcher is already running, click on its iconin the menu bar.

The Service Launcher application w indow appears.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the ToonBoom Process tab.
5. Make sure the Schedule option is checked.
6. Click on Launch to verify that the batch processing service launches successfully through Service
Launcher.
7. Check the Launch when Service Launcher starts option.
8. In the top menu, select Server > Save All Settings.
From now on, the batch processing service w ill launch through Service Launcher w hen you log in.
You can test that your machine is ready to perform batch processing job by entering the follow ing
command in a terminal, replacing <host name> w ith the name of your machine.
$ Status -b -m <host name>313

Chapter 4: Batch Processing

Looking Up the Batch Processing Log on macOS
In order to troubleshoot problems w ith the batch processing service, you can look through its log. This is done
differently depending on w hether you installed the database server as a daemon using Configuration
Assistant, or using Service Launcher.

How to check the log for the batch processing daemon
1. In a terminal, enter the follow ing command:$ less /tmp/com.toonboom.QueueServer.log

How to check the log for the batch processing daemon in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

314

Harmony 22 Installation Guide

Launching Batch Processing Manually on macOSYou can start the batch processing service directly from a terminal. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems. You can view the output of the service
directly in the terminal in w hich you launch it as it starts and handles jobs.

How to start the batch processing service manually
1. In a terminal, enter the follow ing command:$ "/Applications/Toon Boom Harmony 22 [Edition]/Harmony[Edition].app/Contents/tba/macosx/bin/tbprocess" -schedule

315

Chapter 4: Batch Processing

Stopping and Restarting the Batch Processing Daemon on macOSIf you installed batch processing as a daemon using the Configuration Assistant, you can stop it and restart itusing the launchctl command line tool. If you installed it using Service Launcher, you can stop it and restart
it manually in Service Launcher.

How to stop and restart the batch processing daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload/Library/LaunchDaemons/com.toonboom.QueueServer.plist
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo launchctl load
/Library/LaunchDaemons/com.toonboom.QueueServer.plist

How to stop and restart the batch processing daemon in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

316Harmony 22 Installation Guide

Interrupting a Batch Processing Task on macOS
Control Center w ill allow you to cancel a batch processing task before it starts by deleting it from the queue,
but if you delete a batch processing task w hile it is already processing, it w ill still finish in the background.
Vectorizing tasks are added to the queue on a per-draw ing basis. This means that if you w ant to interrupt thevectorization of a scene, you can simply stop the batch processing service and clear the queue in Control
Center. How ever, rendering tasks are added to the queue on a per-scene basis. Therefore, the only w ay tointerrupt the rendering of a scene w hile it is currently rendering is by interrupting the Harmony process that isrendering the scene.

IMPORTANTYou should only interrupt a batch processing task w hen it is necessary, such as w hen an extremely
lengthy task w as started by accident and is liable to delay the other tasks.

How to interrupt a batch processing job
1. In a terminal, enter the follow ing command:$ pgrep tbprocess
The command w ill output the process ID (pid) of the batch processing service (tbprocess).
2. Enter the follow ing command to get the process ID of the child process of the batch processing
service, replacing <pid> w ith the process ID of the batch processing service:$ pgrep -P <pid of tbprocess>This outputs the process ID of the shell in w hich the batch processing job is being ran.
3. Enter the same command, but this time, put the process ID of the child process of the batchprocessing service.
$ pgrep -P <pid of shell>
This outputs the process ID of the Harmony session that is rendering the job.
4. Enter the same command, but again, put the process ID returned by the last command instead:$ pgrep -P <pid of Harmony>This either outputs nothing or, if Harmony is rendering a movie file, the process ID of the media
server creating the movie file.
5. Enter the follow ing command follow ed by the process IDs for the shell, the Harmony session and,if applicable, the utility creating the movie file:$ sudo kill -SIGKILL <pid of shell> <pid of Harmony> <pid of media
server>317

Chapter 4: Batch Processing

TIP
You can execute each command in one go by copying and pasting the follow ing line to theterminal:$ TBPROCESSPID=$(pgrep tbprocess) && TBSHELLPID=$(pgrep -P$TBPROCESSPID) && TBHARMONYPID=$(pgrep -P $TBSHELLPID) &&TBMEDIAPID=$(pgrep -P $TBHARMONYPID); sudo kill -SIGKILL$TBSHELLPID $TBHARMONYPID $TBMEDIAPID

NOTE
The job you interrupted w ill still appear in the queue w ith the Processing status in Control
Center. You w ill need to delete the job manually from the queue to clear it up.

318

Harmony 22 Installation Guide

Uninstalling the Batch Processing Daemon on macOSIf you installed batch processing as a daemon using the Configuraton Assistant, you can uninstall it using thelaunchctl command line tool. If you installed it using Service Launcher, you can uninstall it in Service
Launcher.

How to uninstall the batch processing daemon
1. In a terminal, enter the follow ing command:$ sudo launchctl unload -w/Library/LaunchDaemons/com.toonboom.QueueServer.plist
The daemon w ill no longer launch on boot.
2. If you w ant, you can delete the daemon permanently w ith the follow ing command:$ sudo rm /Library/LaunchDaemons/com.toonboom.QueueServer.plist

How to uninstall the batch processing daemon in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the top menu, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

319

Chapter 4: Batch Processing

Installing the Batch Processing Service on GNU/LinuxOn GNU/Linux, you can install the batch processing service by enabling its daemon to make it launch on bootas user usabatch, or Service Launcher to make it launch w hen the current user logs in.
Installing the Batch Processing Daemon on GNU/Linux

321

Running the Batch Processing Service on Log- In on GNU/Linux323

Checking the Batch Processing Log on GNU/Linux

325

Launching Batch Processing Manually on GNU/Linux

326

Stopping and Restarting the Batch Processing Daemon on GNU/Linux

327

Interrupting a Batch Processing Task on GNU/Linux

328

Uninstalling the Batch Processing Daemon on GNU/Linux

329

320

Harmony 22 Installation Guide

Installing the Batch Processing Daemon on GNU/LinuxThe Harmony installer for GNU/Linux alw ays installs daemon scripts on your machine, but does not enable
them by default. Hence, there are tw o approaches to installing the batch processing daemon:l

By enabling the daemon that w as already installed w ith Harmony using the chkconfig command.

l

By running the Harmony installation script w ith the -p parameter.

This daemon runs through the user usabatch, so this user must be created prior to installing the daemon.

NOTE
The follow ing steps indicate how to make batch processing launch on boot, via the user usabatch,
If you prefer, you can make the database server launch on log-in as the logged-in user. For more
information, see Running the Batch Processing Service on Log-In on GNU/Linux on page 323.

How to create the usabatch user on GNU/Linux
1. In a terminal, enter the follow ing command:$ sudo useradd -m usabatch$ sudo passwd usabatch
2. W hen prompted, enter the passw ord you w ant to assign to the user usabatch, then confirm it.
The user usabatch is now created and can be used to run Harmony daemons.

How to enable the batch processing daemon on GNU/Linux
1. In a terminal, enter the follow ing command to enable the W ebCC server daemon:$ sudo chkconfig toonboom_process on
If the command returns nothing, it succeeded. The W ebCC server w ill launch next time you bootthe machine.
2. To launch the W ebCC server daemon immediately, run the follow ing command:$ sudo service toonboom_process start
The command w ill report w hether it succeeded or failed.

321

Chapter 4: Batch Processing

How to enable the batch processing daemon using the Harmony installation script
1. In a terminal, navigate to the directory w here you dow nloaded the installation package.
$ cd ~/Downloads
2. Extract the package's contents in the directory.
$ tar -xvzf ./name-of-package.tar.gz
3. Sw itch to the directory in w hich the package's contents w ere extracted.
$ cd name-of-package
4. Run the installer w ith the -d parameter:$ sudo ./install -p
5. W hen prompted, confirm that you w ant to proceed w ith the installation.
The installation script w ill enable and start the batch processing daemon. You can test that yourmachine is ready to perform batch processing job by entering the follow ing command in a terminal,
replacing <host name> w ith the name of your machine.
$ Status -b -m <host name>322Harmony 22 Installation Guide

Running the Batch Processing Service on Log- In on GNU/LinuxThe traditional w ay of running the batch processing service is by running the server as a W indow s service or
daemon. This means the service launches in the background as soon as the machine boots, and starts
processing the queue even if nobody is logged in to the computer.
Using Service Launcher, it is possible to configure the batch processing service to launch as the currently
logged-in user, w hen they log in. This means that your machine w ill only process jobs w hen the user is logged
in.
Although this may seem impractical, it may be preferable for security reasons. Harmony services are run under
the user usabatch, an user w ith administrator privileges. W hen using Service Launcher, the logged-in user
does not need to have administrator privileges to run services.
Before configuring Service Launcher to run the batch processing service, the w indow s service that launches it
must be disabled, so as to avoid launching tw o instances of the batch processing service simultaneously.

NOTE
W hile daemons run regardless of w ho is logged in and even w hen no user is logged-in, Service
Launcher w ill only run w hen the user for w hich it w as specifically configured is logged in. Thismeans that if you w ant Service Launcher to launch w hen any user is logged in, you must configure
it for each user that has access to the machine.

How to disable the batch processing daemon on GNU/Linux
1. In a terminal, enter the follow ing command:$ sudo service toonboom_process stop$ sudo chkconfig toonboom_process off
The batch processing daemon w ill stop and w ill no longer launch on boot.

How to configure the batch processing daemon to launch on user log- in
1. Make sure you are currently signed-in as the user w ho w ill run the service.

NOTE
This user w ill need to be logged in for the service to be running. The user does not needto have administrator privileges.

323

Chapter 4: Batch Processing

2. Do one of the follow ing:l

If Service Launcher is not running, in the GNOME top menu, select Applications > Harmony
22 [Edition] >lService Launcher.

If Service Launcher is already running, click on its iconin the system tray.

The Service Launcher application starts.
3. In the Application parameters section of the Preferences tab, make sure that the Launch on login
option is checked, so that services configured in Service Launcher automatically launch w hen you
log in to your account.
4. Select the ToonBoom Process tab.
5. Make sure the Schedule option is checked.
6. Click on Launch to verify that the batch processing service launches successfully through Service
Launcher.
7. Check the Launch when Service Launcher starts option.
8. In the top menu, select Server > Save All Settings.
From now on, the batch processing service w ill launch through Service Launcher w hen you log in.
You can test that your machine is ready to perform batch processing job by entering the follow ing
command in a terminal, replacing <host name> w ith the name of your machine.
$ Status -b -m <host name>324Harmony 22 Installation Guide

Checking the Batch Processing Log on GNU/Linux
In order to troubleshoot problems w ith the batch processing daemon, you can look through its log. This isdone differently depending on w hether you installed the database server as a daemon or using Service
Launcher.

How to check the log for the batch processing daemon
1. In a terminal, enter the follow ing command:$ less /tmp/tbprocess.log

How to check the log for the batch processing daemon in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. In the bottom half, select the Log tab.
5. Click on the View Complete Log button in the bottom-right corner.

325

Chapter 4: Batch Processing

Launching Batch Processing Manually on GNU/LinuxYou can start the batch processing service directly from a terminal. This is usually not practical for a production
environment, but it can be very useful w hen troubleshooting problems. You can view the output of the service
directly in the terminal in w hich you launch it as it starts and handles jobs.

How to start the batch processing daemon manually
1. In a terminal, enter the follow ing command:$ /usr/local/ToonBoomAnimation/harmony[Edition]_22/lnx86_
64/bin/tbprocess -schedule326Harmony 22 Installation Guide

Stopping and Restarting the Batch Processing Daemon on GNU/LinuxIf you installed batch processing as a daemon, you can stop it and restart it using the service command line
tool. If you installed it using Service Launcher, you can stop it and restart it manually in Service Launcher.

How to stop and restart the batch processing daemon
1. In a terminal, enter the follow ing command:$ sudo service toonboom_process stop
2. W hen you are ready to start the server again, enter the follow ing command:$ sudo service toonboom_process start

TIP
You can also restart the service instantly w ith the follow ing command:$ sudo service toonboom_process restart

How to stop and restart the batch processing daemon in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. Click on Stop.
5. W hen you are ready to start the server again, click on Launch.

327

Chapter 4: Batch Processing

Interrupting a Batch Processing Task on GNU/Linux
Control Center w ill allow you to cancel a batch processing task before it starts by deleting it from the queue,
but if you delete a batch processing task w hile it is already processing, it w ill still finish in the background.
Vectorizing tasks are added to the queue on a per-draw ing basis. This means that if you w ant to interrupt thevectorization of a scene, you can simply stop the batch processing service and clear the queue in Control
Center. How ever, rendering tasks are added to the queue on a per-scene basis. Therefore, the only w ay tointerrupt the rendering of a scene w hile it is currently rendering is by interrupting the Harmony process that isrendering the scene.

IMPORTANTYou should only interrupt a batch processing task w hen it is necessary, such as w hen an extremely
lengthy task w as started by accident and is liable to delay the other tasks.

How to interrupt a batch processing job
1. In a terminal, enter the follow ing command:$ pgrep tbprocess
The command w ill output the process ID (pid) of the batch processing service.
2. Enter the follow ing command to kill all processes started by the batch processing service, w hichw ill end any current batch processing job. Replace <pid of tbprocess> w ith the process ID of
the batch processing service, obtained w ith the previous command.
$ sudo pkill -SIGKILL -P <pid of tbprocess>

NOTE
The job you interrupted w ill still appear in the queue w ith the Processing status in Control
Center. You w ill need to delete the job manually from the queue to clear it up.

328

Harmony 22 Installation Guide

Uninstalling the Batch Processing Daemon on GNU/LinuxIf you installed batch processing as a daemon, you can uninstall it using the chkconfig command line tool. If
you installed it using Service Launcher, you can uninstall it in Service Launcher.

How to disable the batch processing daemon
1. In a terminal, type in the follow ing commands to stop, then disable the daemon:$ sudo service toonboom_process stop$ sudo chkconfig toonboom_process off
The batch processing daemon w ill stop and w ill no longer launch on boot.

How to uninstall the batch processing daemon in Service Launcher
1. Make sure you are currently signed in as the user running the service.
2. In the system tray, click on the Service Launcher

icon.

The Service Launcher application opens.
3. Select the ToonBoom Process tab.
4. Click on Stop.
5. Uncheck the Launch when Service Launcher starts option.
6. In the top menu, select Server > Save All Settings.

329

Chapter 4: Batch Processing

Setting Up Default Schedules
W hen you first set up your Harmony system, it is a good idea to set up a default batch processing schedule.
You can modify this schedule later based on the operating needs of your studio.
If you have not created any environments, there w ill not be any environments for you to start up.
You must start up a default schedule for every environment you create in the Harmony database.

NOTE
Maintaining a limited number of environments w ill make it easier to set up and manage batchprocessing queues. For example, you can create four environments, like test, commercials, andone environment per features or series.

How to define the default batch processing schedule
1. Open a command prompt or Terminal and type:> Setdef
Follow the onscreen instructions to set up the environment for batch processing by selected
machines on the Harmony netw ork.
2. At the next prompt, enter the name of the machine on w hich you w ant to set up batch processing:
INPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all

TIP
If you w ant to create a schedule for all machines in the machine list, enter all.

3. At the follow ing prompt, type in y if you w ant to add more machines to the schedule, or n if you aredone selecting machines to schedule.
DO YOU WANT TO INPUT MORE MACHINES
4. At the next prompt, type in y if you w ant the machines to be able to vectorize scanned draw ings, orn if you don't.
is vectorize work allowed?
5. At the next prompt, type in y if you w ant the machines to be able to render scenes, or n if you don't.
is render work allowed?

330

Harmony 22 Installation Guide

6. At the next prompt, you must select the environments for w hich the selected machines w illperform batch processing jobs. The machine w ill only vectorize or render jobs that come fromscenes in the selected environment.
INPUT A SET OF DATABASE ENVIRONMENTS
The prompt w ill display a list of environments. Each environment is listed as a number follow ed bya name. In the prompt, you must type in the number of each environment for w hich this machine
should perform batch processing jobs, separated by spaces, like so:> 1 3 12 34
7. At the next prompt, determine if you w ant batch processing to be enabled or disabled for theselected machines and environment. Typically, you w ould w ant to enable batch processing byentering ON, but this command can also be used to disable batch processing for machines andenvironments by entering OFF.
input ON or OFF
The utility w ill immediately output the new status of the selected machines, in this format:
Machinemachine-nameStatus
ON/OFF

vec
*

ren
*

environments
env env env

pri*

Time of Last Update
Mon Jan 01 12:00:00 2018

NOTES
l

The environments enabled for the machine are listed using a 3 letters abbreviation.
The key for each abbreviation is printed out before the status of the machines.

l

An asterix under the vec column indicates that the machine is enabled forvectorizing.

lAn asterix under the ren column indicates that the machine is enabled for
rendering.

l

An asterix under the pri column indicate that the machine has priority.

331

Chapter 4: Batch Processing

Testing Batch Processing
To verify that batch processing is w orking, send a few frames from a scene to be rendered by the Harmony
module.

How to test batch processing
1. Open the Control Center and select the environment and job that contains the scene to render.
2. Select the scene, right-click on the sample scene in the Scenes section panel and select Send to
Rendering.
The Render W rtie Nodes dialog box opens.

3. In the Range section, select Selected Frames.
4. In From and To field, enter a short range of frames, such as 1 to 5.
5. Click on OK.
An message appears indicating that the scene w as sent to the queue.
6. Click OK to close the message .
7. In Control Center, select the environment containing the scene you just sent to the rendering
queue.
8. In the top menu, select Environment > Render Queue.
The Render Queue dialog opens and displays a list of the scenes in its queue. The scene you sent torendering should start out w ith the status Pending, then sw itch to Processing and finally toCompleted.

332

Harmony 22 Installation Guide

Vectorization of Scanned Drawings
Before you can paint a scanned draw ing in Harmony, you must convert it to a vectorized image format. The
vectorizing process converts the draw ings from a bitmap format to a vector line-based format.
Manually Vectorizing Scenes or Elements

334

Viewing Drawing Vectorization Lists

335

Modifying Vectorize Queue Entries

337

333

Chapter 4: Batch Processing

Manually Vectorizing Scenes or Elements
Normally, w hen you scan draw ings, Harmony automatically vectorizes them (sends them to the Vectorize
queue). How ever, you can also use the Send to Vectorize command to reprocess all draw ings for a particularelement. Vectorizing prepares images for painting by creating vector files. You w ould only have to manuallysend scenes to be vectorized in special cases such as:lProcessing images that w ere not scanned w ith the Scan modulelReprocessing a scene due to unrecoverable paint errors

How to manually vectorize all the drawings for scenes or elements
1. Select a scene from the Scenes list or an element from the Elements list.
If you selected a scene, Harmony vectorizes all draw ings for all elements of that scene.
If you selected an element, Harmony vectorizes all its draw ings.
2. Depending on the component you selected, do one of the follow ing:lSelect Scene > Send to Vectorize or right-click and select Send to Vectorize.

lSelect Element > Send to Vectorize or right-click and select Send to Vectorize.

The Confirm dialog box appears.
3. Click Yes to vectorize all the selected draw ings.
The Control Center module sends all draw ings in the scene or element to the Vectorize queue. To
verify how the processing is progressing, display the vectorize queue.

334

Harmony 22 Installation Guide

Viewing Drawing Vectorization Lists
The Vectorize queue displays all the draw ings that the system is converting to a vector-based format. Afterthe vectorization of a draw ing is finished, the completed draw ing disappears from the Vectorize queue.

How to view the list of drawings being vectorized
1. Select an environment name from the list, then select Environment > Vectorize Queue.
The Vectorize Queue w indow appears.

2. From the Sort By menu, select how to sort entries in the queue:‣

State: Sorts the entries based on the item's status (Pending, Pending-E, Processing, orCompleted)‣

Entry time: Sorts the entries based on the time you send them for vectorization.

‣

Job, Scene, etc.: Sorts the entries based on their parent jobs and scenes.

‣

JobID: Sorts the entries based on their unique job ID.

3. If the Vectorize queue has too many entries, you can select a specific job, scene, element, or
draw ing that is in the queue. Select the items you w ant to display in the queue from the Showmenu, w hich displays all items in the Control Center node's database, not just the ones that havedraw ings being vectorized.
‣

Jobs: Selects the specific job in the queue or one that has scenes currently being vectorized. To
see all the jobs, select All Jobs.

‣

Scenes: Selects the specific scene that is in the queue or currently being vectorized. To see all
the scenes in a job, select All Scenes.

4. Select the states you w ant to display in the queue from the Show States options:‣

Pending: Displays the items w aiting to be vectorized.

335

Chapter 4: Batch Processing‣

Error: Displays the items w here the system found an error and has stopped vectorizing them(displays Pending-E as the item's state).

‣

Processing: Displays the items that the Harmony is currently processing.

‣Completed: Displays the items that w ere vectorized. How ever, the Control Center node usually
removes completed items from the Vectorize queue, so this option is inactive.

‣

Show All States: Displays all the items, regardless of their state.

5. In the Refresh section, select how often you w ant the queue to check for the latest entries.
‣

Hold: Displays no new entries to the queue once the button is activated.

‣

Monitor: Automatically displays new entries at the interval you enter in the Every ## secs field.

6. To see any related errors for each entry in the queue, select the Show Error Messages option.
If the Control Center node detected any errors w hile it prepares the draw ings, it displays PendingE in the State column. These errors can occur if there are files missing, computers are unavailable,or data cannot be found.

NOTE
Most of these errors w ould occur if the system is improperly configured. Therefore, yoursystem administrator needs to reconfigure the system to correct the error. If you get aPending-E error, see your system administrator.

336

Harmony 22 Installation Guide

Modifying Vectorize Queue Entries
W hen you have a list of entries in your queue, you can modify them in one of the follow ing w ays:l

Click the Change State to Pending button to change the status of the selected entries in the queue
from Processing to Pending. After a job becomes Pending, the next available machine w ill process theentry.
If you w ant to remove the entry from the queue, select the Pending entry and click Delete. If the entry is
processing, you can delete the entry from the queue but the processing w ill not stop until it iscompleted.
You can only modify an entry in the queue w hile it is pending (check the State column in the queue list).
You cannot modify a job that is being processed.

lClick the Change Priority button to change the selected draw ings' processing priority in the queue.
W hen the New Priority dialog box appears, increase or decrease the draw ing's priority.

lClick the Delete button to delete the selected draw ings from the queue. W hen you remove a draw ing
from the queue, the request is cancelled only.

337

Chapter 4: Batch Processing

Rendering Scenes
W hen you have finished w orking on some scenes, you can send them to the Render queue via Control Centeror Harmony, by w ay of the Send to Rendering command. This command allow s you to send one or morescenes for rendering to the Batch Processing machine.
You can also use Harmony to render scenes, but since you must open each scene individually in Harmony, you
can only send one scene to render at a time.
After rendering a scene, you can mark it as completed using the Change Stage command in the Scene menu.
After you render all the scenes for a particular Job, you can mark the Job as completed using the Change Stage
command in the Job menu.

NOTE
Changing the job's stage from In Production to Completed only hides the job in the Control Centerw indow .

Viewing Render Queues

339

Modifying Render Queue Entries

341

338

Harmony 22 Installation Guide

Viewing Render Queues
The Render queue displays all the scenes from the selected environment that the system is rendering. Afterthe system renders a scene, the State of the rendered scene changes to Complete or Completed w ith Errors
and the scene remains in the queue. If you w ant to remove the rendered scenes, you must select them and use
the Delete button.

How to view the scenes being rendered
1. Select an environment name from the list, then select Environment > Render Queue.
The Render Queue w indow appears.

2. Select how to sort the entries in the queue from the Sort By.
‣

State: Sorts the entries based on the item's status (Pending, Pending-E, Processing, Completed
w ith Errors, or Completed).

‣

Entry Time: Sorts the entries based on the time you sent them for rendering.

‣Job, Scene, etc.: Sorts the entries based on their parent jobs and scenes.

‣

JobID: Sorts the entries based on their unique job id.

3. Select the components you w ant to display in the queue from the Show .
‣Jobs: Select the specific job you w ant to see.

‣

Scenes: Select the specific scene you w ant to see.

4. Select the states you w ant to display in the queue from the Show States options.
‣

Pending: Displays the items w aiting in the queue.

339

Chapter 4: Batch Processing‣

Processing: Displays the items that currently processing.

‣Completed: Displays completed items.

‣

Error: Displays the items that contains errors that stopped processing (displays Pending-E as
the item's state).

‣

Show All States: Displays all items, regardless of their state.

5. In the Refresh section, select how often you w ant the queue to check for the latest entries.
‣

Hold: Displays no new entries to the queue once the button is activated.

‣

Monitor: Automatically displays new entries at the interval you enter in the Every ## secs field.

6. Select the Show Error Messages option to see any related errors for each entry in the queue.

NOTE
If the Control Center node detects any errors w hile processing the scenes, it displays"Pending-E" in the State column. Errors can occur if there are files missing, computers areunavailable, or data cannot be found.
Many of these errors can occur if the system is improperly configured. If you get a Pending-E
error, see your system administrator as the system may need to be reconfigured.

340

Harmony 22 Installation Guide

Modifying Render Queue Entries
After you have a list of entries in your queue, you can modify them in one of the follow ing w ays:
1. Change their state in the queue. This allow s you to update the status of a scene, or set of scenes, in thequeue from Processing (w hich means it is being rendered) to Pending (w hich means the scenes are
w aiting to be rendered). After you set a job to Pending, the job remains in the queue until a machine
becomes available and takes the job or you delete it from the queue.
lClick the Change State to Pending button to change the status of the selected entries in
the queue from Processing (or Completed) to Pending.

2. Change the scene's processing priority. This allow s you to change the order in w hich the systemrenders the scenes.
l

Click Change Priority to change the selected scene's processing priority in the queue.

l

W hen the New Priority dialog box appears, use the scroll bar to increase or decrease thescene's render priority.

3. Remove scenes from the Render queue. This allow s you to cancel the render command on selectedscenes.
l

Click the Delete button to delete the selected entries from the queue.

You can only modify an entry in the render queue w hile it is pending (check the State column in the queue list);
you cannot modify a job that is being rendered.
If you must change something about the scene's draw ings, you must w ait until the rendering is complete.
Then make your changes and send it to the Render queue.

NOTE
If you absolutely must stop the rendering process, you can kill the render process in W indow s,
GNU/Linux or macOS.

341

Chapter 4: Batch Processing

Batch Processing Schedules
Once the basic vectorization and rendering batch processing is started, there are more advanced options
possible such as advanced scheduling.
By creating a schedule to monitor the batch processing, you can determine w hich machines perform the batchprocessing and w hen they do it. Each batch processing machine on your netw ork has its ow n set of schedules
and you can view and modify them from any machine on the netw ork.
There are three types of schedules available for a machine:lSupervisory Schedule: Assigns a one-time batch processing job to a machine. For example, you candefine a Supervisory schedule for a machine to perform batch processing w ork for the next four hours.
Of the three types of schedules, Supervisory schedules have the highest priority. If you define a
Supervisory schedule for a specific period of time on a machine, it w ill perform the batch processing
w ork according to that schedule, regardless of w hat the Periodic and Default schedules define for that
period of time.

lPeriodic Schedule: Assigns recurring batch processing jobs. For example, you can define a Periodic
schedule for a machine to perform batch processing only on Saturdays and Sundays.
Periodic schedules use the days of the w eek, so you can have batch processing occurring each w eek on
specific days.
In terms of priority, a Periodic schedule supersedes a Default schedule, but not a Supervisory Schedule.
If there is a Periodic schedule active on a machine, then it performs this type of batch processing
according to its Periodic schedule before it uses the Default schedule.

lDefault Schedule: Defines w hich jobs the machine can process if there are no other schedules defined.
Default schedules have the low est priority, and are used only w hen Supervisory and Periodic schedules
are not present or do not define the w ork to be done for a particular period of time.

W hen creating or modifying a schedule, you must supply the follow ing information:lDates and times for w hich the schedule applieslMachine(s) for w hich the schedule applieslW hether batch processing is ON or OFF (w hether that machine does or does not perform batchprocessing w ork)l

The type of batch processing to be done: Vectorize and/or Renderingl

The environments for w hich batch processing processes the artw orkl

The priority of the environments to be batch processed (optional)

For any given machine, you can define, clear and view the Supervisory and Periodic schedules. You can only
modify or view the Default schedule for a machine.
You can also shut dow n and start up environments to stop and start batch processing of a particularenvironment on a machine(s). W hen you shut dow n an environment, you are overriding w hatever you already342Harmony 22 Installation Guide

scheduled for it (according to each type of schedule). Therefore, you w ill stop any batch processing jobs on theenvironment until you start that environment again. You can also view a schedule's status to see an overview
of all schedules set for a specified time.
Displaying the Schedule Status

344

Reading the Schedule Status List

346

About Default Schedules

348

Displaying Default Schedules

349

Reading Default Schedule Status Lists

351

Modifying Default Schedules

353

About Periodic Schedules

356

Displaying Periodic Schedules

357

Setting Periodic Schedules

359

Clearing Periodic Schedules

363

About Supervisory Schedules

364

Displaying Supervisory Schedules

365

Setting Supervisory Schedules

367

Clearing Supervisory Schedules

371

About Environment Shut Down

372

Shutting Dow n Environments

373

Starting Up Environments

375

Harmony Scheduling Utilities

377

343

Chapter 4: Batch Processing

Displaying the Schedule Status
You can monitor w hich machines are vectorizing or rendering animation data. The schedule status displays an
overview of w hat each render or vectorize machine is processing at a specific time. The overview also displaysa machine's status based on the highest priority schedule set for the time you select.

You can display this status list by typing the Status command in a Command Shell or Terminal on any
machine in the netw ork. W hen you run the Status command, you must specify the day and time for w hich
you w ant to view the schedule status.

How to display the schedule status list
1. Open a Command Shell or Terminal and type:
Status
You can view the status for one or more machines by listing them after the Status command(instead of all the machines, w hich is the default). You can also type a prefix to search for machines
w ith names that start w ith the same prefix.
Example:lStatus hp: Show s the status for all machines that begin w ith "hp".

l

Status cm hp6: Show s the status for all machines that begin w ith "cm" and for hp6.

l

Status: Show s the status for all machines.
W hen you press Enter/Return, you are prompted to specify the time for w hich you w ant to view theschedule status.
INPUT BEGIN TIME in 24-hr. format [15:17]:344

Harmony 22 Installation Guide

2. Type the time you w ant to view the status for in 24-hour format. If you press Enter/Return w ithout
specifying a time, the system uses the time displayed in brackets (the current time).
W hen you press Enter/Return, the system prompts you for the day for w hich you w ant to view thestatus.
input day [wed]:
3. Type the day of the w eek for w hich you w ant to view the status (you can not enter dates). If youpress Enter/Return w ithout entering a day, the system uses the day displayed in brackets (thecurrent day).
The schedule status for the time and day you specified appears.

345

Chapter 4: Batch Processing

Reading the Schedule Status List
W hen you display the Schedule Status list, the information appears in three separate sections:l

Key: Lists the abbreviations the status schedule uses for the environments, the tw o types of batchprocesses you can schedule on a machine, and the abbreviations the other columns use in the list.

lSchedule Status: Displays the processing status of each vectorizing or rendering machine in the
netw ork.

lSummary: Displays a summary of w hich machines are performing a specific type of batch processing(vectorize or render). The summary appears directly below the Schedule Status section.

The follow ing table describes the contents of the Schedule Status list:
Column title

Description

R

Displays an R for each machine that has the batch processing service running on
it. The batch processing service must be running in order to execute batchprocessing tasks.
If an R does not appear for a machine, the Schedule Status list displays w hat
w ould be scheduled if the batch processing service w as running on it.

Indicates if an environment is shut dow n for batch processing on that machine.
You can specify that certain machines do not process environments by selecting
the machines that should be shut dow n (or turned off).
SD
An asterisk (*) appears in the SD column to indicate that one or moreenvironments have been shut dow n for that machine—see About Environment
Shut Dow n.

Machine

Displays the name of the netw orked machine that is configured to accept batchprocessing jobs.

Indicates w hether the machine is available for batch processing.
State

On: The machine is scheduled to batch process.
Off: The machine is not scheduled (for the time you specified) to batch process.

Lists the type of batch processing the machine is scheduled to perform (vectorize
and/or batch processing ).
vecstatusIf an asterisk (*) appears in these columns for a machine, then this type of batchprocessing is scheduled for this machine.
If a machine is scheduled to do both types of batch processing, the machine
performs both types alternatively; it processes an entry from the Vectorize queue,346

Harmony 22 Installation Guide

vectorizes the data, and then take an entry from the Render queue.

Displays the environments scheduled to be batch processed on a machine.
Environments

The machine batch processes only the data from the environments listed in thiscolumn.

Displays the priority level for batch processing on a machine. You can prioritize
environments so that one machine can perform the batch processing before
another.
pri
If an asterisk (*) appears in the pri column, the environments are prioritized forthat machine. The priority order for the environments appears in theEnvironments column (reads from left to right, highest to low est priority).

Displays the date and time of the next status change for that machine, according
to the defined batch processing schedules.
nexteventTime

For example, even though the hickey machine is off at the moment, the Timecolumn indicates that the next time its status w ill change is at 12:53 on
W ednesday, March 8. This indicates that a Periodic or Supervisory schedule is set
for this machine.

347

Chapter 4: Batch Processing

About Default Schedules
A Default schedule sets batch processing for a machine w hen no other schedules are in effect. For example, if
there are no Supervisory or Periodic schedules that affect a particular machine on Monday at 9:00 a.m., theDefault schedule determines the type of batch processing that this machine performs at that time.
Every Harmony system machine uses a Default schedule to determine w hen it should perform batchprocessing. You can display or modify the Default schedules for any machine in the Harmony system.
Displaying Default Schedules

349

Reading Default Schedule Status Lists

351

Modifying Default Schedules

353

348

Harmony 22 Installation Guide

Displaying Default Schedules
W hen you display a Default schedule, you can see all the batch processing machines on the netw ork andw hen they are scheduled to perform batch processing w ork. The Default schedule also displays the type ofbatch processing w ork (vectorize or render) and w hich environments are scheduled for the processing w ork.
After you display the Default schedule, you can modify it to change the time, type of batch processing, or
environments to process—see Modifying Default Schedules.

How to display the Default schedule
1. In a GNU/Linux shell, type:Showdef
You are prompted for the machine(s) w hose Default schedule you w ant to see.
INPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all [all]:

2. Select the machines you w ant to view by typing the name of a single machine, a prefix (to select a
range of machines that start w ith the same prefix), or all to view all the Default schedules for all
the machines.
If you press Enter/Return w ithout specifying a machine, the command uses the machine name thatappears in brackets.

NOTE
If you type a prefix, a list of machines that contain that prefix appears. Type the numbers that
correspond to the machines you w ant to view .
For example, if you have three machines that start w ith "hi", you can type hi as a prefix. The
system w ould then display a list of all the machines that start w ith"hi":input a set of machines, or hit return to indicate all thesemachines:
1 = hickey, 2 = highlander, 3=high-definition
You can press Enter/Return to select all the machines in the list or select specific machines bytyping their corresponding numbers.

You are asked if you w ant to view more machines.
DO YOU WANT TO INPUT MORE MACHINES (y/n) [n]:3. Decide if you w ant to view more environments and machines.
lType y to select more machines.

lType n to not select any more machines.

The Default schedule for the selected machines appears.

349

Chapter 4: Batch Processing

350Harmony 22 Installation Guide

Reading Default Schedule Status Lists
W hen you display the Default schedule status list, the system displays the information in tw o sections:l

Key: Lists the abbreviations the status schedule uses for the environments, the tw o types of batchprocesses you can schedule on a machine, and the abbreviations the other columns use in the list.

lSchedule Status: Displays the processing status of each vectorizing or rendering machine in the
netw ork

The follow ing table describes the contents of the Schedule Status list:
Column Title

Description

Machine

Displays the name of the netw orked machine that is configured to accept batchprocessing jobs.

Indicates w hether the machine is available for batch processing.
Status

On: The machine is scheduled to batch process.
Off: The machine is not scheduled (for the time you specified) to batch process.

Lists the type of batch processing the machine is scheduled to perform (vectorize
and/or batch processing ).
vec

If an asterisk (*) appears in these columns for a machine, then this type of batchprocessing is scheduled for this machine.

ren
If a machine is scheduled to do both types of batch processing, the machine
performs both types alternatively; it processes an entry from the Vectorize queue,
vectorizes the data, and then take an entry from the Render queue.

Displays the environments scheduled to be batch processed on a machine.
Environments

The machine batch processes only the data from the environments listed in thiscolumn.

Displays the priority level for batch processing on a machine. You can prioritize
environments so that one machine can perform the batch processing before
another.
pri
If an asterisk (*) appears in the pri column, the environments are prioritized forthat machine. The priority order for the environments appears in theEnvironments column (reads from left to right, highest to low est priority).

Time of Last Update

The Default schedule also indicates the last time the schedule w as modified foreach machine.

351

Chapter 4: Batch Processing

This final column displays the date and time that the Default schedule w as lastmodified for each machine.

352

Harmony 22 Installation Guide

Modifying Default Schedules
W hen you are ready to change the Default schedule, you must specify the follow ing information:l

The machine(s) you w ant to updatel

The type of batch processing w ork you w ant to assignl

The environments to process

After modifying the Default schedule, use the Showdef command to view your changes—see Displaying
Default Schedules.

How to change a Default schedule
1. In a Terminal, Command Prompt or Linux shell, type:
Setdef
2. Press Enter/Return.
You are prompted for the machine(s) w hose Default schedule you w ant to modify.
INPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all [all]:

3. Select the machines you w ant to view by typing the name of a single machine, a prefix (to select a
range of machines that start w ith the same prefix), or all to view all the Default schedules for all
the machines.
If you press Enter/Return w ithout specifying a machine, the command uses the machine name thatappears in brackets.

NOTE
If you type a prefix, a list of machines that contain that prefix appears. Type the numbers that
correspond to the machines you w ant to view .
For example, if you have three machines that start w ith "hi", you can type hi as a prefix. The
system w ould then display a list of all the machines that start w ith"hi":input a set of machines, or hit return to indicate all thesemachines:
1 = hickey, 2 = highlander, 3=high-definition
You can either press Enter/Return to select all the machines in the list or you can select certain
machines by typing their corresponding numbers.

You are asked if you w ant to modify the Default schedule for more machines.
DO YOU WANT TO INPUT MORE MACHINES (y/n) [n]:4. Decide if you w ant to change the Default schedule on other machines.

353

Chapter 4: Batch ProcessinglType y to select more machines and press Enter/Return.

You are prompted to select other machines (see step 1 of this procedure).
lType n to not select any more machines and press Enter/Return.

You are prompted to decide if you w ant vectorizing w ork performed on the machine.
INPUT TYPE OF WORK ALLOWED is vectorize work allowed (y/n) [yes]5. Decide if you w ant the machines to perform vectorizing w ork on the selected machines.
lType y to schedule vector batch processing and press Enter/Return.

lType n to not schedule vector batch processing and press Enter/Return.

l

If you press Enter/Return w ithout entering y or n, the prompt uses the answ er show nin brackets.

The system then prompts you to select if you w ant rendering w ork performed on the machine.
is render work allowed (y/n) [yes]6. Select if you w ant the machines to perform rendering w ork on the selected machines.
lType y to schedule Render batch processing and press Enter/Return.

lType n to not schedule Render batch processing and press Enter/Return.

l

If you press [Enter] w ithout entering y or n, the prompt uses the answ er show n inbrackets.

You are prompted to select the environments to be scheduled for batch processing.
INPUT A SET OF DATABASE ENVIRONMENTS
1 = Production, 2 = Tutorials, 3 = Commercials default - [Production
Commercials]

All the environments in your system appear in this list, each one assigned to a number.
7. Type the number that corresponds to the environment(s) you w ant to schedule and press
Enter/Return. If you press Enter/Return w ithout typing anything, the environments listed inbrackets are used.
If you select more than one environment, the system asks if you w ant to establish a priority.
should processing of the DBenv's be prioritized? (y/n) [yes]You can prioritize your environments so that batch processing w orks on the highest priority
environment first. If you do not define a priority, the batch processing does an equal amount ofw ork for each environment.
The order in w hich you type the environment numbers can determine their batch processing priority
in the schedule (the first environment you type has the highest priority). How ever, the order in354

Harmony 22 Installation Guidew hich you type the environments is not important if you do not w ant to prioritize the environments(by answ ering no to the system prompt).
In this example, if you w ant to schedule only the Production and Tutorials environments forbatch processing, you w ould type: 1 2, indicating that Production has a higher priority than
Tutorials for batch processing.
8. Decide if you w ant to assign a priority to the environments you selected. If you press Enter/Returnw ithout entering anything, the system uses the answ er show n in brackets.
lType y to prioritize batch processing.

lType n to not prioritize batch processing.

The system prompts you to schedule the status of the machine(s).
input ON or OFF [on]:9. Decide if you w ant to apply the Default schedule right aw ay, making the machines available
immediately.
lType on to make the machines available for batch processing according to theirdefined Default schedules and press Enter/Return.

lType off to make the machines unavailable for batch processing, regardless of theirdefined Default schedules, and press Enter/Return.

l

If you press Enter/Return w ithout entering on or off, the prompt uses the answ ershow n in brackets.

The Default schedule for the specified machines is set. The new schedule appears.

355

Chapter 4: Batch Processing

About Periodic Schedules
The Periodic schedule is an optional schedule that defines a recurring period of time w hen a machine w illperform batch processing. You can create a Periodic schedule by specifying a day of the w eek (Monday,
Tuesday, etc.) and the machine w ill perform batch processing on the specified days for every w eek.
A Periodic schedule lists batch processing jobs for w hich you must define a start and end date, and time. Eachjob has its ow n set of batch processing parameters that are independent of the other jobs in the schedule.
For example, you can create a Periodic schedule for a machine so that it performs batch processing every nightfrom 20:00 that evening to 08:00 the follow ing morning. Therefore, the machine w ould not perform batchprocessing w ork during the day w hen the users w ould be present.

NOTE
In terms of priority, the Periodic schedule is betw een the Default and Supervisory schedules. If
there are no Supervisory schedules for a machine, or the Supervisory schedule does not define thew ork to be done for a particular period of time, the machine uses the Periodic schedule.
How ever, if you have an active Supervisory schedule , the machine follow s this schedule before it
follow s either the Periodic or Default schedules.

Displaying Periodic Schedules

357

Setting Periodic Schedules

359

Clearing Periodic Schedules

363

356

Harmony 22 Installation Guide

Displaying Periodic Schedules
W hen you display a Periodic schedule, you can see all the batch processing machines that use this scheduleand w hen they are scheduled to perform the batch processing. The Periodic schedule also displays the type ofbatch processing w ork (vectorize or render) and the environments that are scheduled for the processing w ork.
After you display the Periodic schedule, you can modify it to change the time, type of batch processing, or
environments to process—see Setting Periodic Schedules.

NOTE
You can display the Periodic schedule for only one machine at a time.

How to display a Periodic schedule
1. In a GNU/Linux shell, type:
Showper
You are prompted for the machine w hose Periodic schedule you w ant to view .
INPUT MACHINE [hickey]:

2. Type the name of the machine for w hich you w ant to define a Periodic schedule.
If you press Enter/Return w ithout specifying a machine, the command uses the machine name thatappears in brackets.

NOTE
You can combine these tw o steps by adding the name of the machine you w ant to view at theend of the Showper command.
For example, if the machine you w ant to view is called hickey, then you w ould type thefollow ing command in a GNU/Linux shell to view its Periodic schedule.

Showper hickey
The Periodic schedule for that machine appears.

357

Chapter 4: Batch Processing

358

Harmony 22 Installation Guide

Setting Periodic Schedules
W hen you are ready to modify your Periodic schedule, you need to specify the follow ing information:l

The machine(s) for w hich you w ant to create or update the periodic schedule(s)lThe type of batch processing w ork you w ant to assignl

The environments to processl

W hen to start and stop the batch process

You can add jobs to the schedule if a Periodic schedule already exists for a particular machine, or you can clear
out any pre-existing jobs before setting new jobs in the schedule. You can clear a Periodic schedule w ithout
setting any new jobs—see Clearing Periodic Schedules on page 363.

How to define a Periodic schedule on a machine

NOTE
If you press Enter/Return w ithout entering anything, the command uses the information thatappears in brackets of commands.

1. In a GNU/Linux shell, type:
Setper
You are prompted for the machine(s) w hose Periodic schedule you w ant to modify.
INPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all [all]:

2. Select the machines you w ant to modify by typing the name of a single machine, a prefix (to selecta range of machines that start w ith the same prefix), or all to modify all the Periodic schedules for
all the machines.

NOTE
If you type a prefix, a list of machines that contain that prefix appears. Type the numbers that
correspond to the machines you w ant to view .
For example, if you have three machines that start w ith "hi", you can type hi as a prefix. The
system w ould then display a list of all the machines that start w ith"hi":input a set of machines, or hit return to indicate all thesemachines:
1 = hickey, 2 = highlander, 3=high-definition
Press Enter/Return to select all the machines in the list or select specific machines by typing
their corresponding numbers.

359

Chapter 4: Batch Processing

You are asked if you w ant to modify the Periodic schedule on more machines.
DO YOU WANT TO INPUT MORE MACHINES (y/n) [n]:3. Do one of the follow ing:lType y to select more machines.

lType n to not select any more machines.

You are prompted to clear the existing schedule before defining new entries.
WOULD YOU LIKE TO CLEAR THE SCHEDULE OF PRE-EXISTING ENTRIES? (y/n) [n]:4. Do one of the follow ing:lType y to remove any existing schedules on the machine(s).

lType n to preserve any existing schedules on the machine(s). The system w ill add
your new entries to the existing set of entries.

You are prompted to schedule any new entries in your Periodic schedule.
WOULD YOU LIKE TO SCHEDULE ANY ENTRIES? (y/n) [y]5. Do one of the follow ing:lType y to schedule new entries. Proceed to the next step to define the schedule.

lType n to not schedule any new entries. This cancels the Setper command w ithoutscheduling any new entries.

6. If you typed y to the previous prompt, you are prompted to activate or deactivate the selected
machines.
input ON or OFF [on]:lType on to activate the Periodic schedule for the selected machines.

lType off to deactivate the Periodic schedule for the selected machines. The machine(s) w ill not perform any Periodic batch processing, regardless of w hat the other
Periodic entries have been scheduled.

You are prompted to decide if you w ant vectorizing w ork performed on the machine.
INPUT TYPE OF WORK ALLOWED is vectorize work allowed (y/n) [no]7. Do one of the follow ing:lType y to schedule Vector batch processing.

lType n to not schedule Vector batch processing.

The system prompts you to decide if you w ant rendering w ork performed on the machine.
is render work allowed (y/n) [yes]360Harmony 22 Installation Guide

8. Do one of the follow ing:lType y to schedule Render batch processing.

lType n to not schedule Render batch processing.

You are prompted to select the environments to be scheduled for batch processing. All theenvironments in your system appear in this list, each one assigned to a number.
INPUT A SET OF DATABASE ENVIRONMENTS
1 = Production, 2 = Tutorials, 3 = Commercials default - [Production
Commercials]

9. Type the number that corresponds to the environment(s) you w ant to schedule and press[Enter/Return]. If you select more than one environment, the system asks if you w ant to establish apriority.
should processing of the DBenv's be prioritized? (y/n) [yes]You can prioritize your environments so that batch processing w orks on the highest priority
environment first. If you do not define a priority, the batch processing does an equal amount ofw ork for each environment.
The order in w hich you type the environment numbers can determine their batch processing priority
in the schedule (the first environment you type has the highest priority). How ever, the order inw hich you type the environments is not important if you don't w ant to prioritize the environments(by answ ering no to the system prompt).
In this example, if you w ant to schedule only the Production and Tutorials environments forbatch processing, you w ould type: 1 2, indicating that Production has a higher priority than
Tutorials for batch processing.
10. Select if you w ant to assign a priority to the environments you selected.
lType y to prioritize batch processing.

lType n to not prioritize batch processing.

The scheduler prompts you to define the time and day w hen to start the Periodic batch processing.
INPUT BEGIN TIME in 24-hr. format [15:17] input day [wed]:

11. Type the time (in 24-hour format) and day (in day of the w eek format) w hen to begin batchprocessing and press [Enter/Return].
The scheduler prompts you for the end time.
INPUT END TIME in 24-hr. format: input day [thu]:

12. Type the time (in 24-hour format) and the day (in day of the w eek format) w hen to stop the batchprocessing and press Enter/Return.

361

Chapter 4: Batch Processing

A summary of the job you just scheduled appears. The scheduler then prompts you to confirm thatyou w ant to enter this job in the schedule.

13. Do one of the follow ing:lType y to add this job into your Periodic schedule.

lType n if you do not w ant to add this job into your Periodic schedule.

The scheduler gives you the opportunity to add another job to your Periodic schedule.
DO YOU WANT TO SCHEDULE ANOTHER EVENT (y/n) [y]14. Do one of the follow ing:lType y to add another job and press Enter/Return. Repeat steps 7 to 13.

lType n if you do not w ant to enter another job and press Enter/Return.

W hen you finish adding jobs to the Periodic schedule, a summary of the entire Periodic scheduleappears.

362

Harmony 22 Installation Guide

Clearing Periodic Schedules
If you decide that you do not need to have any recurring batch jobs, you can clear the scheduled jobs from the
Periodic schedule. Once the Periodic schedule is empty, the batch jobs in the Default schedule come into
effect.
You can clear existing jobs from a Periodic schedule w ithout creating any new jobs. How ever, w hen you clear
a Periodic schedule, you clear all the jobs that exist for that schedule.

How to clear a Periodic schedule
1. Follow steps 1 to 3 in Setting Periodic Schedules on page 359.
2. Type y w hen you reach the follow ing prompt:
WOULD YOU LIKE TO CLEAR THE SCHEDULE OF PRE-EXISTING ENTRIES? (y/n) [n]3. Type n w hen you reach the follow ing prompt:
WOULD YOU LIKE TO SCHEDULE ANY ENTRIES? (y/n) [y]This clears the Periodic schedule and displays an empty schedule, confirming that the system
cleared the jobs.

363

Chapter 4: Batch Processing

About Supervisory Schedules
A Supervisory schedule forces a machine to perform batch processing for a non-recurring period of time. This
type of schedule, like the Periodic schedule, is optional. If you have a Supervisory schedule active for a periodof time, the machine performs batch processing according to that schedule before it references the Periodic or
Default schedules.
For example, you could force a machine to perform only Vectorize batch processing for the next four hours,
ignoring any other scheduled type of batch processing during that time.
A Supervisory schedule consists of a list of batch processing jobs for w hich you must define a start and end
date and time. Each job has its ow n set of batch processing parameters that are independent of the other jobs
in the schedule.

NOTE
The Supervisory schedule holds the highest priority level, superseding the Periodic schedule andDefault schedule. Therefore, if you have an active Supervisory schedule, the machine follow s thisschedule before it follow s the Periodic or Default schedules.

Displaying Supervisory Schedules

365

Setting Supervisory Schedules

367

Clearing Supervisory Schedules

371

364

Harmony 22 Installation Guide

Displaying Supervisory Schedules
W hen you display a Supervisory schedule, you can see all the batch processing machines that use thisschedule and w hen they are scheduled to perform the batch processing. The Supervisory schedule also
displays the type of batch processing w ork (vectorize or render) and the environments that are scheduled forthe processing w ork.
After you display the Supervisory schedule, you can modify it to change the time, type of batch processing, or
environments to process—see Setting Supervisory Schedules.

NOTE
You can display the Supervisory schedule for only one machine at a time.

How to display a Supervisory schedule
1. In a GNU/Linux shell, type:Showsup
You are prompted for the machine w hose Supervisory schedule you w ant to view .
INPUT MACHINE [hickey]:

2. Type the name of the machine for w hich you w ant to define a Supervisory schedule.
If you press Enter/Return w ithout specifying a machine, the command uses the machine name thatappears in brackets.

NOTE
You can combine these tw o steps by adding the name of the machine you w ant to view at theend of the Showsup command.
For example, if the machine you w ant to view is called hickey, then you w ould type thefollow ing command in a GNU/Linux shell to view its Supervisory schedule.
Showsup hickey

The Supervisory schedule for the machine appears.

365

Chapter 4: Batch Processing

366

Harmony 22 Installation Guide

Setting Supervisory Schedules
W hen you are ready to modify your Supervisory Schedule, you need to specify the follow ing:l

The machine(s) for w hich you w ant to create or update the supervisory schedule(s)lThe type of batch processing w ork you w ant to assignl

The environments to processl

W hen to start and stop the batch process

You can add jobs to the schedule if a Supervisory Schedule already exists for a particular machine, or you canclear out any pre-existing jobs before setting new jobs in the schedule. You can clear a Supervisory Schedule
w ithout setting any new jobs (see Clearing Supervisory Schedules on page 371).

How to define a Supervisory schedule on a machine

NOTE
If you press Enter/Return w ithout entering anything, the command uses the information thatappears in brackets of commands.

1. In a GNU/Linux shell, type:Showsup
You are prompted for the machine(s) w hose Supervisory schedule you w ant to modify.
INPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all [all]:

2. Select the machines you w ant to modify by typing the name of a single machine, a prefix (to selecta range of machines that start w ith the same prefix), or all to modify all the Supervisory schedules
for all the machines.

NOTE
If you type a prefix, a list of machines that contain that prefix appears. Type the numbers that
correspond to the machines you w ant to view .
For example, if you have three machines that start w ith "hi", you can type hi as a prefix. The
system w ould then display a list of all the machines that start w ith"hi":input a set of machines, or hit return to indicate all thesemachines:
1 = hickey, 2 = highlander, 3=high-definition
Press Enter/Return to select all the machines in the list or select specific machines by typing
their corresponding numbers.

367

Chapter 4: Batch Processing

You are asked if you w ant to modify the Supervisory schedule on more machines.
DO YOU WANT TO INPUT MORE MACHINES (y/n) [n]:3. Do one of the follow ing:lType y to select more machines.

lType n to not select any more machines.

You are prompted to clear the existing schedule before defining new entries.
WOULD YOU LIKE TO CLEAR THE SCHEDULE OF PRE-EXISTING ENTRIES? (y/n) [n]:4. Do one of the follow ing:lType y to remove any existing schedules on the machine(s).

lType n to preserve any existing schedules on the machine(s). The system w ill add
your new entries to the existing set of entries.

You are prompted to schedule any new entries in your Supervisory schedule.
WOULD YOU LIKE TO SCHEDULE ANY ENTRIES? (y/n) [y]5. Do one of the follow ing:lType y to schedule new entries. Proceed to the next step to define the schedule.

lType n to not schedule any new entries. This cancels the Setper command w ithoutscheduling any new entries.

6. If you typed y to the previous prompt, you are prompted to activate or deactivate the selected
machines.
input ON or OFF [on]:lType on to activate the Supervisory schedule for the selected machines.

lType off to deactivate the Supervisory schedule for the selected machines. The
machine(s) w ill not perform any Supervisory batch processing, regardless of w hat theother Supervisory entries have been scheduled.

You are prompted to decide if you w ant vectorizing w ork performed on the machine.
INPUT TYPE OF WORK ALLOWED is vectorize work allowed (y/n) [no]7. Do one of the follow ing:lType y to schedule Vector batch processing.

lType n to not schedule Vector batch processing.

The system prompts you to decide if you w ant rendering w ork performed on the machine.
is render work allowed (y/n) [yes]368Harmony 22 Installation Guide

8. Do one of the follow ing:lType y to schedule Render batch processing.

lType n to not schedule Render batch processing.

You are prompted to select the environments to be scheduled for batch processing. All theenvironments in your system appear in this list, each one assigned to a number.
INPUT A SET OF DATABASE ENVIRONMENTS
1 = Production, 2 = Tutorials, 3 = Commercials default - [Production
Commercials]

9. Type the number that corresponds to the environment(s) you w ant to schedule and press[Enter/Return]. If you select more than one environment, the system asks if you w ant to establish apriority.
should processing of the DBenv's be prioritized? (y/n) [yes]You can prioritize your environments so that batch processing w orks on the highest priority
environment first. If you do not define a priority, the batch processing does an equal amount ofw ork for each environment.
The order in w hich you type the environment numbers can determine their batch processing priority
in the schedule (the first environment you type has the highest priority). How ever, the order inw hich you type the environments is not important if you don't w ant to prioritize the environments(by answ ering no to the system prompt).
In this example, if you w ant to schedule only the Production and Tutorials environments forbatch processing, you w ould type: 1 2, indicating that Production has a higher priority than
Tutorials for batch processing.
10. Select if you w ant to assign a priority to the environments you selected.
lType y to prioritize batch processing.

lType n to not prioritize batch processing.

The scheduler prompts you to define the time and day w hen to start the Supervisory batchprocessing.
INPUT BEGIN TIME in 24-hr. format [15:17] input day [wed]:

11. Type the time (in 24-hour format) and day (in day of the w eek format) w hen to begin batchprocessing and press Enter/Return.
The scheduler prompts you for the end time.
INPUT END TIME in 24-hr. format: input day [thu]:369

Chapter 4: Batch Processing

12. Type the time (in 24-hour format) and the day (in day of the w eek format) w hen to stop the batchprocessing and press Enter/Return.
A summary of the job you just scheduled appears. The scheduler then prompts you to confirm thatyou w ant to enter this job in the schedule.

13. Do one of the follow ing:lType y to add this job into your Supervisory schedule.

lType n if you do not w ant to add this job into your Supervisory schedule.

The scheduler gives you the opportunity to add another job to your Supervisory schedule.
DO YOU WANT TO SCHEDULE ANOTHER EVENT (y/n) [y]14. Do one of the follow ing:lType y to add another job and press Enter/Return. Repeat steps 7 to 13.

lType n if you do not w ant to enter another job and press Enter/Return.

W hen you finish adding jobs to the Supervisory schedule, a summary of the entire Supervisoryschedule appears.

370Harmony 22 Installation Guide

Clearing Supervisory Schedules
If you decide you don't need to set a Supervisory schedule for your batch processing jobs, you can clear thescheduled jobs from the Supervisory schedule. Once the Supervisory schedule is empty, the batch processing
jobs in the Periodic and Default schedules come into effect.
You can clear existing jobs from a Supervisory schedule w ithout creating any new jobs. How ever, w hen you
clear a Supervisory schedule, you clear all of the jobs that exist for that schedule.

How to clear a Supervisory schedule
1. Follow steps 1 to 3 in Setting Supervisory Schedules on page 367.
2. Type y w hen you reach the follow ing prompt:
WOULD YOU LIKE TO CLEAR THE SCHEDULE OF PRE-EXISTING ENTRIES? (y/n) [n]The Supervisory schedule is cleared. An empty schedule displayed, confirming that the system
cleared the jobs.

371

Chapter 4: Batch Processing

About Environment Shut Down
In some cases, you must shut dow n a machine so it does not process any batch jobs from an environment orfor a specific amount of time. You may w ant to, for example, shut dow n batch processing for all environments
on a single machine so you can reboot the machine. Or you can shut dow n one environment on all machines so
you can move scenes in that environment to other machines.
To determine if an environment is shut dow n on a particular machine, type Status in a Command Shell or
Terminal. If you see an asterisk (*) in the SD column for a particular machine, this means at least one
environment is shut dow n on that machine.
You can view the Supervisory and Periodic schedules for the shut dow n machines to isolate w hichenvironments are shut dow n.
Shutting Down Environments

373

Starting Up Environments

375

372

Harmony 22 Installation Guide

Shutting Down Environments
W hen you shut dow n an environment, this overrides w hatever w as scheduled for that environment (for all
three types of schedules). The environment remains shut dow n until you reinstate it by typing Suenv
command in a Command Shell or Terminal (see Starting Up Environments). You can shut dow n multiple
environments on multiple machines, from any machine in the netw ork.
W hen shutting dow n an environment, the command prompts you for the environments you w ant to close andthe machines on w hich you w ant them to be shut dow n.

How to shut down an environment on a machine
1. In a Command Shell or Terminal, type:
Sdenv
You are prompted for the environments to shut dow n:
INPUT DATABASES TO BE STOPPEDINPUT A SET OF DATABASE Environments
1 = Production, 2 = Tutorials, 3 = Commercials, default = [Production
Tutorials Commercials]
All the Environments appear in this list and each one has its ow n number.
2. Type the number that corresponds to each environment you w ant to shut dow n (separate eachnumber by a space) and press Enter/Return.
You are prompted you for the machine(s) on w hich you w ant the environments to be shut dow n:
INPUT MACHINE ON WHICH THESE DBENV'S ARE TO BE SHUTDOWNINPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all[hickey]:
3. Select the machines that should not process the shut dow n environment by typing the name of asingle machine, a prefix (to select a range of machines that start w ith the same prefix), or all toshut dow n all the environments on all the machines.
If you press Enter/Return w ithout specifying a machine, the command uses the machine name thatappears in brackets.

373

Chapter 4: Batch Processing

NOTE
If you type a prefix, a list of machines that contain that prefix appears. Type the numbers that
correspond to the machines you w ant to view .
For example, if you have three machines that start w ith "hi", you can type hi as a prefix. The
system w ould then display a list of all the machines that start w ith"hi":input a set of machines, or hit return to indicate all thesemachines:
1 = hickey, 2 = highlander, 3=high-definition
Press Enter/Return to select all the machines in the list or select specific machines by typing
their corresponding numbers.

You are prompted to decide if you w ant to shut dow n more machines.
DO YOU WANT TO INPUT MORE MACHINES (y/n) [n]:You are asked if you w ant to shut dow n more environments and machines.
4. Do one of the follow ing:lType y to select more machines.

lType n to not select any more machines.

A summary of the shutdow n appears:
here are the 3 machines you input: hickey weiner garneau
ALL MACHINES HAVE REPORTED. SHUT DOWN COMPLETE.
The Sdenv command w aits for a response from all the selected machines. The Sdenv command
does not terminate a batch process that is currently running on a machine. If a machine is currently
performing a batch process, it w ill not shut dow n until it completes the queue entry.

374

Harmony 22 Installation Guide

Starting Up Environments
W hen you're ready to restart the batch process on an Environment that w as shut dow n, use the Suenv
command. W hen you restart an Environment, you are prompted for the Environments you w ant to start up andthe machines you w ant them to start running on.

NOTE
If you accidentally restart an environment that is already active, nothing happens.

How to start an environment
1. In a Command Shell or Terminal, type:
Suenv
You are prompted for the environments to restart:
INPUT DATABASES TO BE STARTEDINPUT A SET OF DATABASE Environments
1 = Production, 2 = Tutorials, 3 = Commercials, default = []All the environments in your system appear in this list and each one has a number.
2. Type the numbers that correspond to each environment you w ant to restart (separate each number
by a space) and press Enter/Return.
You are prompted for the machine(s) you w ant to process the environments:
INPUT MACHINE ON WHICH THESE DBENV'S ARE TO BE STARTEDINPUT A SINGLE MACHINE NAME, THE PREFIX OF A MACHINE NAME, OR all[hickey]:
3. Select the machines for processing the environment by typing the name of a single machine, aprefix (to select a range of machines that start w ith the same prefix), or all to restart all theenvironments on all the machines.
If you press Enter/Return w ithout specifying a machine, the command uses the machine name thatappears in brackets.

375

Chapter 4: Batch Processing

NOTE
If you type a prefix, a list of machines that contain that prefix appears. Type the numbers that
correspond to the machines you w ant to view .
For example, if you have three machines that start w ith "hi", you can type hi as a prefix. The
system w ould then display a list of all the machines that start w ith"hi":input a set of machines, or hit return to indicate all thesemachines:
1 = hickey, 2 = highlander, 3=high-definition
Press Enter/Return to select all the machines in the list or select specific machines by typing
their corresponding numbers.

You are prompted to decide if you w ant to restart enviroments on more machines.
DO YOU WANT TO INPUT MORE MACHINES (y/n) [n]:4. Do one of the follow ing:lType y to select more machines.

lType n to not select any more machines.

A summary of the started machines appears:
here are the 3 machines you input: hickey weiner garneau
ALL MACHINES HAVE REPORTED. STARTUP COMPLETE.

376

Harmony 22 Installation Guide

Harmony Scheduling Utilities
The follow ing table lists the utilities used by Harmony to configure batch processing schedules and theirparameters.
Command

EffectDisplays the Schedule Status (default for all machines).

Status

Options:[machine]: Limits the display to specified machines (separate machine names w ith spaces).
[prefix]: Limits the display to machines w ith specified prefix.

Showdef

Displays Default schedules.

Setdef

Modifies Default schedules.

Displays Periodic schedule (for a single machine only).
Showper

Options:[machine]: Specifies the machine w hose Periodic schedule you w ant to display.

SetperSets and/or clears Periodic schedule.

Displays Supervisory schedule (for a single machine only).
Showsup

Options:[machine]: Specifies the machine w hose Supervisory schedule you w ant to display.

Setsup

Sets and/or clears Supervisory schedules.

Sdenv

Shuts dow n environments.

Suenv

Starts up environments.

377

Chapter 5: Service Launcher

Chapter 5: Service Launcher
The Service Launcher allow s users w ithout full administrative rights to launch three Toon Boom Harmony
services: ToonBoom Process (for batch rendering and vectorization), Database Server and W ebCC. It w ill also
attempt relaunch services should they stop for any reason.
The topics in this installation guide specify how to perform many tasks w ith Service Launcher. The follow ing
section is a reference guide for the user interface of Service Launcher.
Service Launcher Top Menu

379

Service Launcher Preferences Tab

380

Service Launcher ToonBoom Process Tab

381

Service Launcher Database Server Tab

383

Service Launcher W ebCC Tab

385

Service Launcher Link Tab

387

378

Harmony 22 Installation Guide

Service Launcher Top Menu
Access these menus and their commands from the top menu bar of the Service Launcher w indow .
Menu

ServerCommand

Description

Save All Settings

Select this command to register any changes
made to the options in the Service Launcher.

Select this command to stop all service

Stop All Processes

processes.

Quit

Select this command to quit the Service
Launcher application.

Help

Select this command to launch Toon Boom's
w ebsite, w here you can find various resources
for support.

About

Select this command to open the About Toon
Boom Service Launcher w indow . This w indow
contains version and copyright information.

Help

379

Chapter 5: Service Launcher

Service Launcher Preferences Tab
Use the options available in the Preferences tab to customize the behaviour of the Service Launcher.

Parameter

Description

Services location

Displays the location path of the Service Launcher application on your computer.
You can click on the ellipses button, at the end of the field, to brow se for a newlocation.

Application parameters

Launch on login

Check this option if you w ould like to launch the Service Launcher application
every time you login to your computer. This enables the Display W indow option.

Display w indow

Check this option if you w ould like to the Service Launcher w indow to open w hen
the Service Launcher is launched on login. Otherw ise, the Service Launcher
application w ill run in the background and be accessible to open through yourcomputer's task bar.

Notify me on errors

Check this option if you w ould like to be notified of errors.

Show last lines of log files

Allow s you to enter the maximum number of lines from the bottom of the log filethat you w ould like displayed for the ToonBoom Process, Database Server andW ebCC services.

On error

Allow s you to enter the number of seconds that the Service Launcher should w ait
before trying to relaunch any of services, should they happen to stop.

380

Harmony 22 Installation Guide

Service Launcher ToonBoom Process Tab
The Toon Boom Process allow s a machine to be a batch processing node for your netw ork's vectorizing andrender farm. Process runs in the background and checks the database's queue for any vectorizing or rendering
job it could perform and, if it find any, performs them in the background.

Parameter

Description

Launch button

Click on this button to start the service. The status w ill change from Closed to
Running.

Stop button

This button is enabled w hen the service is running. Click on this button to stop theservice.

Launch w hen Service
Launcher starts

Check this option to automatically launch the ToonBoom Proces service w hen theService Launcher is launched. This bypasses the need to click on the Launchbutton.

Parameters

Debug

Output detailed information about the tasks performed by the process service tothe log, to help debug any issue w ith the service.

Schedule

This option is checked by default. It is strongly recommended that you leave thisoption enabled. It runs the ToonBoom Process service using the scheduler.

381

Chapter 5: Service Launcher

Other Parameters

Help tabCommand line parameters to pass to the service w hen launching it. The Help tab
below contains a list of parameters supported by the service. Once you havemade changes to the list of parameters, you can click on Update Parameters torelaunch the service w ith the new parametes.

This tab lists all the available options for the ToonBoom Process (tbprocess).You
can type these parameters in the Other Parameters field to customize thebehaviour of the service.

This tab records the activity of the service w hile it runs. It only lists up to the
maximum number of lines specified in the Preferences tab.
Log tabl

Clear W indow button: clears the existing log data from the w indow .

lView Complete Log button: launches the Dialog w indow w hich displays
a complete version of the logo information.

382

Harmony 22 Installation Guide

Service Launcher Database Server Tab
The Database Server service manages requests from Harmony Server clients w ho connect to the Harmony
database using Harmony, Paint, Scan or Control Center.

Parameter

Description

Launch button

Click on this button to start the service. The status w ill change from Closed to
Running.

Stop button

This button is enabled w hen the service is running. Click on this button to stop theservice.

Launch w hen Service
Launcher starts

Check this option to automatically launch the Database Server service w hen theService Launcher is launched. This bypasses the need to click on the Launchbutton.

Parameters

Debug

Output detailed information about the tasks performed by the datbase server tothe log, to help debug any issue w ith the server.

Keep Alive

Check this option if you w ould like the Database Server to automatically restart in
the event that it crashes or fails. You can select the w ait period before relaunch in
the Preferences tab.

383

Chapter 5: Service Launcher

Other Parameters

Command line parameters to pass to the service w hen launching it. The Help tab
below contains a list of parameters supported by the service. Once you havemade changes to the list of parameters, you can click on Update Parameters torelaunch the service w ith the new parametes.

Update Parameters

Click on this after making changes to the Other Parameters field to stop andrelaunch the service w ith the new parameters.

This tab lists all the available options for the database server. You can type these
Help tabparameters in the Other Parameters field to customize the behaviour of theservice.

This tab records the activity of the service w hile it runs. It only lists up to the
maximum number of lines specified in the Preferences tab.
Log tabl

Clear W indow button: clears the existing log data from the w indow .

lView Complete Log button: launches the Dialog w indow w hich displays
a complete version of the logo information.

384

Harmony 22 Installation Guide

Service Launcher W ebCC Tab
The W ebCC server service allow s people to connect to the Harmony database using a w eb brow ser, to export
scenes, w ork on them using Harmony Stand Alone, then upload their changes back to the database.

Parameter

Description

Launch button

Click on this button to start the service. The status w ill change from Closed to
Running.

Stop button

This button is enabled w hen the service is running. Click on this button to stop theservice.

Launch w hen Service
Launcher starts

Check this option to automatically launch the W ebCC service w hen the Service
Launcher is launched. This bypasses the need to click on the Launch button.

Parameters

Authentication

Check this option to display the Login screen w hen users connect to W ebCC.
Users must have a valid username and passw ord.

Port

8080 is the default port number for connection. If it w as modified, you can enter
your custom port number in its place.

Other Parameters

Command line parameters to pass to the service w hen launching it. The Help tab
below contains a list of parameters supported by the service. Once you have385

Chapter 5: Service Launcher

made changes to the list of parameters, you can click on Update Parameters torelaunch the service w ith the new parametes.

Update Parameters

Help tabClick on this after making changes to the Other Parameters field to stop andrelaunch the service w ith the new parameters.

This tab lists all the available options for the W ebCC server.You can type theseparameters in the Other Parameters field to customize the behaviour of theservice.

This tab records the activity of the service w hile it runs. It only lists up to the
maximum number of lines specified in the Preferences tab.
Log tabl

Clear W indow button: clears the existing log data from the w indow .

lView Complete Log button: launches the Dialog w indow w hich displays
a complete version of the logo information.

386

Harmony 22 Installation Guide

Service Launcher Link Tab
The Link tab allow s you to configure the Toon Boom Harmony Link Server to launch w hen logging-in. The link
server allow s W indow s clients to create symbolic links on macOS or GNU/Linux servers, w hich is part of thescene creation routine on a Harmony database.

NOTE
This tab is only available on macOS and GNU/Linux.

Parameter

Description

Launch button

Click on this button to start the service. The status w ill change from Closed to
Running.

Stop button

This button is enabled w hen the service is running. Click on this button to stop theservice.

Launch w hen Service
Launcher starts

Check this option to automatically launch the Link server service w hen the Service
Launcher is launched. This bypasses the need to click on the Launch button.

Parameters

Debug

Output detailed information about the tasks performed by the link server to thelog, to help debug any issue w ith the server.

387

Chapter 5: Service Launcher

Parameter

Description

Other Parameters

Command line parameters to pass to the service w hen launching it. The Help tab
below contains a list of parameters supported by the service. Once you havemade changes to the list of parameters, you can click on Update Parameters torelaunch the service w ith the new parametes.

Update Parameters

Click on this after making changes to the Other Parameters field to stop andrelaunch the service w ith the new parameters.

Help tabThis tab lists all the available options for the link server. You can type theseparameters in the Other Parameters field to customize the behaviour of theservice.

This tab records the activity of the service w hile it runs. It only lists up to the
maximum number of lines specified in the Preferences tab.
Log tabl

Clear W indow button: clears the existing log data from the w indow .

lView Complete Log button: launches the Dialog w indow w hich displays
a complete version of the logo information.

388