Using the Terminal to troubleshoot Smoke

Summary

Certain advanced Smoke troubleshooting or configuration tasks may require you to use the Mac OS X Terminal. This article gives you an introduction to the Terminal (also known as "shell") and an overview of some basic UNIX system commands and of some custom Smoke commands and scripts you may need to use.

Warning! Use the Terminal very carefully. Make sure you know exactly what a command does before running it. Some commands may damage your operating system or cause important loss of data, if used improperly.
Autodesk takes no responsibility for loss of data or for configuration issues arising from an improper use of a terminal command or script.

Starting the Terminal

Run the terminal from the Applications / Utilities folder.
If you need to open an additional terminal window, click the terminal icon in the dock and select New Window.

When the terminal opens, it displays the command prompt.
The command prompt indicates the hostname of your Mac (highlighted in yellow in the example below), followed by the name of the current directory (highlighted in light green) and by the name of the currently logged in user (highlighted in purple):
MTLC02DR2JQDC7C:Smoke Common Utilities demo$  

The commands you type will appear after the $ sign.  

Running and stopping commands and scripts

Running a command or script
To run a command, type it in the Terminal, followed by any parameters required and press Enter.
Make sure that the command and all its parameters are on the same line.

Keep in mind that anything you type in a Terminal is case sensitive.
You can also copy / paste commands to and from the Terminal.  

To run a script, type its full directory path (for example /usr/discreet/sw/sw_ping), or use the cd command to go to the directory where the script is located and type the script name preceded by ./
For example: cd /usr/discreet/sw ./sw_ping  

Stopping a command or script
Most commands and scripts automatically exit and return you to the command line prompt once the task is completed.
There are however commands and scripts that must be stopped manually. (such as the ping command, for example). 
To manually stop a command or script press Control+C.
Closing the Terminal window also stops any commands or scripts currently running in it, including any non-Terminal applications that were open by a command or script in that Terminal window.  

Running commands as superuser

Certain commands or scripts may require superuser privileges. (The superuser is also known as root).

To run a command or script as superuser type sudo before the actual command:
sudo <command>
or
sudo ./<script name>

Enter your password when prompted and the command will be executed with superuser privileges.

Note that sudo does not log you in as superuser permanently. To run additional commands or scripts with superuser privileges, you must use sudo again before each command.
You will not be asked for a password if you issue a new sudo command within 5 minutes of the previous one.

You can use the stand-alone sudo -i command to remained logged in as superuser until you close the Terminal window, but we do not recommend using this approach, for security reasons. 

Going to a directory (folder)

To go to a specific directory, use the cd command followed by the directory name.
For example: cd /usr

Note: If the directory you are trying to access has spaces in its name, use a backslash before each space to "escape" it. For example: cd /Applications/Autodesk/Smoke\ Common\ Utilities

You can also go directly to a subdirectory.
For example: cd /usr/discreet

To go to the parent of the current directory type:
cd ../

To go two levels up type:
cd ../../

To go to the top directory of the entire filesystem (also called the root directory), type:
cd /

To go to the home directory of the currently logged in user, type:
cd ~

To find out the full path of the directory you are currently in, type:
pwd 

Listing the contents of a directory

To list the contents of the current directory type:
ls

To list the contents of another directory, type ls followed by the directory path.
For example: ls /usr/discreet/

To get details on each file and subdirectory, as well as to see hidden files type:
ls -lah

Each line in the command output is similar to the following example:
0 drwxrwxr-x  3 root  wheel   102B Oct 21 14:53 License Server Selector.app

Details on each file / folder include:

• file permissions (drwxrwxr-x in the example above)
  Note: d indicates that the entry is a directory. Mac OS X apps with the .app extension are actually directories containing the app executable and other associated files.
• number of subdirectories in each directory (3)
• file owner (root)
• file owner's group (wheel)
• file size in Bytes, Kilobytes, Megabytes, Gigabytes (102B)
• the date and time when the file was created or last modified (Oct 21 14:53)
• the name and extension of the file (License Server Selector.app)

Note: To find a specific file in a directory with many entries, you can use the grep command to filter out the results of the ls command.
For example, to find if there is a file called test in the current directory, type: ls | grep test
The | character (called a "pipe") tells the Terminal to pass the output of the ls command through the grep command.

Creating a copy of a file or directory

We recommend creating a back-up copy of any configuration file you plan to edit in the Terminal.

To copy a file, type:
cp <file path> <new file path>
For example: cp test.cfg test.cfg.bkp

To copy a directory, type:
cp -r <directory path> <new directory path>
For example: cp -r myFolder myFolderCopy

Viewing the contents of a text file

To view the contents of a text file, such as a configuration file or a log file, type:
cat <file path>
For example: cat /usr/discreet/sw/log/sw_probed.log

The cat command outputs the entire contents of the text file.

If the file is very long and you are looking for a specific word in the file, you can use the grep command to filter the output of the cat command.
For example:  cat /usr/discreet/sw/log/sw_probed.log | grep error
This will output all the lines in the file that contain the word you are looking for (case sensitive).

Another option is to use the more command to view the text file one screen at a time:
more /usr/discreet/sw/log/sw_probed.log
Press Space to move to the next "page" in the file.
Press Q to quit the viewer.

Editing a text file

To edit a text file, such as a configuration file, you can use the nano command line text editor.

Warning! We strongly recommend creating a backup copy of a configuration file before editing it.

To open a file in nano, type:
nano <file path>

Note that for many configuration files you may need to use sudo to gain superuser privileges:
sudo nano <file path>

Once the file opens in nano, use the arrow keys to navigate to the place you want to edit (you cannot use the mouse).

Lines that begin with a pound sign (#) in configuration files are comments and are ignored by Smoke.
Adding a pound sign before a line is a good way of quickly disabling a setting.

When you have finished editing, press Control+o to save the file, then press Y to confirm overwriting the file.
Press Control+x to exit nano.

Getting the list of running processes

To get the list of running apps and background services, type:
ps -ef

You can use grep to filter the output and check if a given service is running.
For example: ps -ef | grep wiretap

Forcing a process to exit
If an application or background process becomes unresponsive and you cannot terminate it from the Mac OS interface, you can force it to quit by using the following procedure.
Warning! Terminating a process in this way will cause all unsaved data to be lost. Proceed at your own risk. 

1. Find the process in the list of running processes:
   ps -ef | grep <part of process name>
   Note: If you don't know the process name, use ps -ef without grep and then manually search through the list of processes.
    
2. Once you have found the process you want to terminate, take note of its PID number (highlighted in the example below):
   0 17036   1  0  0:00.81 ??  0:01.28 /usr/discreet/wiretapgateway/wiretapgateway
    
3. Type the following command to terminate the process:
   sudo kill -9 <pid>
    
   E.g., using the PID in the previous example:
   sudo kill -9 17036

Testing network connectivity

You can test network connectivity using the ping command:
ping <target>

Where <target> can be the name or IP address of another computer on your network, of your network router, or of a public Internet server.

Pinging another computer on your network enables you to check that the two computers "see" each other over the network.
Pinging your network router enables you to verify that your Mac is properly connected to the local network.
Pinging a major Internet server or Web site enables you to verify that your Mac has an Internet connection.

For example:
ping 192.168.0.1
ping myMac
ping google.com

If the network works properly, you should not get a "Destination Host Unreachable" message.
Press Control+c to stop the ping command.

What is "localhost"?

When troubleshooting Smoke you may often hear about "localhost" or the "127.0.0.1" IP address.

localhost is an internal-only name that your Mac uses to refer to itself. This is different from your Mac's normal network name.
127.0.0.1 is an internal-only IP address that corresponds to localhost. This is different from your Mac's regular network IP address.

Contrary to your Mac's regular name and IP address, which may change every time you join a new network, the name localhost and the IP address 127.0.0.1 never change.
Because 127.0.0.1 is an IP that always refers to your Mac, Autodesk recommends using it in your Stone+Wire or local license server configuration, instead of using your Mac's regular name and IP address.

Important Smoke directories and files

• The Smoke application and main configuration utilities are located in the /Applications/Autodesk directory.
• The bulk of Smoke's internal binaries, configuration files, logs and command-line utilities, as well as the Smoke project database and clip libraries are located in the /usr/discreet/ directory.
• Stone+Wire configuration files are located in the /usr/discreet/sw/cfg directory.
  See the following KB article for descriptions of the Stone+Wire configuration files: Stone and Wire Configuration Files
• Smoke's logs are located in the /usr/discreet/log directory.
• See the following KB article for details: Understanding Application Log Files
• Stone+Wire logs are located in the /usr/discreet/sw/log directory.
  See the following KB article for details: Overview of Stone and Wire Log Files
• The log files for Smoke's ADLM license server are located in the /var/log/autodesk directory.
• The license configuration files are in the /var/flexlm and /usr/local/flexnetserver directories.
  See the following KB article for details: Smoke for Mac OS X ADLM Licensing - Technical Details

Smoke-specific commands and scripts

Refer to one of the following KB articles for instructions on Smoke-specific commands and scripts:

• Launching Smoke from a Terminal
• Managing Smoke Services via Command Line
• Advanced Stone and Wire command-line utilities
• Starting and Stopping Stone and Wire from a Terminal
• Setting the hostname or computer name from the terminal
• Checking the MD5 Checksum of a Downloaded File
• Manually Uninstalling Autodesk Smoke for Mac OS X