Basic Functionality

Start at the beginning by downloading a fresh copy of NoMAD on a fresh Mac. It doesn’t matter if the Mac is bound to AD or not; NoMAD will work either way.

You can find the download here, in the Support section of the website.

1. Launch NoMAD. The binary is signed, as all good applications should be, and can be run from any location. The application’s icon is a caribou, the most nomadic land mammal in the world.
2. If you’re not bound to AD, you’ll be presented with a Preferences window. The only field you need to fill out at this time is the “AD Domain” field at the top.
3. If you are bound to AD, you will not see the Preferences window, as NoMAD will automatically determine your AD Domain and use that. You can change this later by using the Preferences window, or through other means.
4. Once NoMAD has launched, you’ll see a triangle icon in the Menu Bar at the top of your screen. If you are not able to reach your AD Domain, you’ll see “Not Connected” next to the icon. If you can reach your domain, you’ll see the same triangle without any text. Finally, if you already have a Kerberos ticket for the current user, you will see a green check mark in the triangle. The icons are shown below.
5. If the icon has “Not Connected” next to it, sign in to your VPN or otherwise connect to your organization’s network so that your AD Domain Controllers (DCs) are able to be reached by the system running NoMAD. NoMAD will automatically detect when the network has changed and will update accordingly.
6. Once connected, you can sign in to NoMAD if you do not have a green check mark in the NoMAD icon in the menu bar. Do this by using the “Sign In” option on the menu. If you’re unable to contact the DCs, you won’t be able to use the “Sign In” menu item.
7. This will activate the Sign In window where you can sign in as an AD user. You can simply use the user’s short name, or you can use their full user@domain.com handle. Note that there is no need to enter the NT Domain before the user name.
8. Upon successful authentication, you will now have a Kerberos TGT for that AD user and will be able to sign in to all Windows SSO resources, which may include websites, file servers, and some applications.
9. If your user has a password expiration policy, the number of days until that user’s password expires will be shown on the menu bar next to the NoMAD icon and on the second line of the NoMAD menu itself. If the user does not have an expiration date, then no text will be next to the NoMAD icon and the second line of the NoMAD menu will show “password does not expire”.
10. To remove your SSO credentials, you can use the “Sign Out” menu item.

User Interaction

Next, you’ll want to test additional user functionality beyond a simple sign in and sign out. To do that, we’ll walk through the rest of the menu items. To begin, sign in to AD with NoMAD so that you have a valid user already logged in. Your NoMAD menu should look similar to this:

1. If the currently signed in user has a password expiration date, hovering your mouse over the NoMAD icon in the menu bar will show you the actual date and time that their password expires.
2. Holding down the “option” key while clicking on the NoMAD menu will show the expiration date of your current Kerberos TGT, and the AD Domain Controller that NoMAD is currently using for all LDAP lookups in the second item on the NoMAD menu.
3. Test renewing your Kerberos ticket by using the “Renew Tickets” menu item. This will renew the ticket with AD and ensure that your Kerberos ticket has the longest duration possible. You can verify this by using the klist tool on the command line, or by holding down the “option” key again to view the ticket lifetime in the second line of the NoMAD menu. It may take a few seconds for the lifetime to update in the menu.
4. Next, change the user’s password by using the “Change Password” menu item. This will bring up the “Change Password” window and allow you to enter your old password and then the new password twice. When you click the “Change Password” button, NoMAD will change the user’s AD password via Kerberos. 
5. If no errors occur, the user’s AD password will be changed and any password expiration dates will be updated. Note that most AD environments will only allow a password to be changed once every 24 hours. Also note that this will not change the password of the local user account on the Mac by default; that can be enabled using a preference key if desired.
6. Next, use the “Lock Screen” button to sleep the Mac’s screen. If you have the system configured to require password when waking the screen, you will be prompted to enter it.
7. If you have a) Jamf Self Service, b) Munki Managed Software Center, or c) Lan Rev Agent installed on your system, the “Get Software” menu item will be available and will launch the appropriate self service application when clicked. If you don’t have any of those applications, this menu item will not appear; you can specify a different application to be launched from this menu by setting a preference key.
8. Next, use the “Get Help” menu item. This will open a web browser to http://www.apple.com/support by default. However, similar to many other menu items in NoMAD, you can set this to an application, a script, another webpage, or even a Bomgar remote support session via the preference keys.
9. Next, select the “Preferences” menu item. You will find the most commonly used options here, as well as the only options that are accessible through the UI. The AD Domain will already be set, and the Kerberos Realm will most commonly be set to the uppercase version of the AD Domain. NoMAD will automatically fill this in if you haven’t. The next two text fields are for specifying a Windows Certificate Authority and Certificate template for getting certificates from AD. The “Use Keychain” check box allows NoMAD to store your AD password in your keychain and automatically log you in. The “Renew Ticket” check box determines whether or not NoMAD automatically renews your Kerberos tickets. The text field next to this box allows a user to set how many seconds between renewing the Kerberos ticket. Finally, the “Show Home Folder” has NoMAD show a user’s home folder, as specified in their AD profile, in the menu.
10. The “Quit” menu item will quit NoMAD while keeping any Kerberos tickets intact on your system.

How NoMAD Deals with UPCs

If the UPCAlert key is set in the NoMAD preferences, NoMAD compares the last known password set date against the password set date in the user’s AD record. This happens every 15 minutes, on every network change, or whenever the user clicks on the NoMAD menu.

If a discrepancy between these dates is found, NoMAD shows a notification in the macOS Notification Center to alert the user that his or her password was changed in AD outside of NoMAD on that machine. By selecting that notification, the user is given the opportunity to sign in to NoMAD again in order to validate their new password. At that point, NoMAD will use the user’s old password in the Keychain to update the Keychain with the new password, as on AD-bound machines, the user password should already have been updated.

Important Considerations

For this to work, the user must be storing their password in the Keychain (the UseKeychain setting in the NoMAD preferences). NoMAD must also be up and running on a computer when the notification is sent. If the user is signed out of his or her Mac when this happens, NoMAD is unable to do anything to fix it. In addition, the Mac needs to be on the AD domain for the alert to be triggered.

The UPCAlert state is a unique situation for NoMAD, because on AD-bound machines the user password will be automatically updated by the act of checking the password, so checking the user password is not enough to determine that the user is in this state.

Other Notes

NoMAD has the option of triggering an action to be done at the time of a UPCAlert. This is set with the UPCAlertAction preference key.

NoMAD can use a user’s Kerberos ticket to connect to a Windows Web Certificate Authority and obtain a certificate for that user. This method works well, but does come with a few caveats that you should keep in mind:

1. If you’re bound to AD, you’re probably better off using a profile via MDM or other management tool to get a user and/or machine certificate. Apple has put a lot of work into making this pretty seamless. The primary use of NoMAD in this case is for unbound machines, although the process will work well either way.
2. NoMAD can only get a user certificate. Since NoMAD runs in user space, it has no access to any machine account credentials. Also, if you’re not bound to AD, you most likely don’t even have a machine account in AD in the first place.
3. This method requires a Windows CA to have web enrollment turned on. This is a standard feature of Windows Server, but it’s not always turned on. The web enrollment also needs to be set to allow for either Kerberos authentication or Windows Authentication in Windows parlance.

Set Up

To have NoMAD get a certificate, you need to set the DNS name of the Web CA and the Certificate Template to use in NoMAD’s preferences. The DNS name is just the name; do not include http/https or any trailing path, e.g. dc1.nomad.test, not https://dc1.nomad.test/certsrv.

With these two options set, a new “Get Certificate” menu will show in the NoMAD menu, if a user is signed into AD. Selecting this item will cause a CSR to be generated locally and sent to the Web CA. Assuming that everything is in order, the CA will sign the CSR and send that back to the Mac. NoMAD will then add the signed certificate to the private key in the user’s keychain.

Additional Options

Check our page on Preferences for more information on how to automatically get a certificate, how to automatically renew a certificate, and how to ensure that the private key is set as non-exportable.

Troubleshooting

The simplest way to test this is to go to the Web CA using a web browser on the Mac. Safari is typically the easiest, as it requires no configuration to use Kerberos. With the DNS name of the CA, add /certsrv to get to the web enrollment page. You can then request a certificate using a certificate template through the web interface.

Some items of note here:

1. The Mac needs to have full trust of the SSL certificates used on the Web CA for NoMAD to work. If your web browser tells you the connection is untrusted, you’ll need to ensure the certificates are fully trusted.
2. If the web CA prompts for authentication and you already have Kerberos tickets for the user, the Web CA needs to be using Windows Authentication. This can be changed using the IIS tools on the Windows server.
3. The certificate template to be used has to be available to the user that is requesting the certificate. This can be configured in the certificate template snap-in that’s part of the MMC on the Windows server.
4. If the Web CA’s certs are trusted but the certificate pull still doesn’t work, use nscurl --ats-diagnostics --verbose https://server.domain.com from the CLI on the Mac with your Web CA’s DNS name substituted in. This will determine whether the TLS security on the Web CA is on par with what macOS is expecting. Often, the Web CA may be set up with TLS 1.0 or other older protocols. You’ll need to be on TLS 1.2 for NoMAD to use the Web CA.
5. Finally, look at the CA on the Windows server and look for failed certificate requests. Other common issues can be discovered here, such as missing a set email for the user, or other configuration problems.

Here are a few tips and tricks to get things back on the straight and narrow when you do encounter these scenarios.

Verbose Logging

The first step in any troubleshooting process is to run NoMAD from the command line and put it into verbose mode. It’s perfectly acceptable to do this while other copies of NoMAD are running; you’ll just have multiple icons in the menu bar.

To launch NoMAD in verbose, open up a Terminal window and put the full path to the NoMAD binary, not just the application bundle with -v. For example, if NoMAD is installed in the Applications folder you’d use this in Terminal:

/Applications/NoMAD.app/Contents/MacOS/NoMAD -v

This will launch NoMAD and put all logs directly into the terminal window that’s already open. This makes it very simple to gather the NoMAD logs and see events happen in real time.

Most issues are at least identifiable in the logs. Some things may jump out, as verbose logging should record a lot of events and information as NoMAD works. The other issue that’s typically encountered is an “illegal instruction 4” error. This typically represents a variable in the code that was expected to have a value, but is empty. NoMAD has a number of checks for these, but there’s always the chance that either we’ve left something out, or you have a setting that we’ve never seen missing a value before.

Additional CLI Options

There are some other flags you can use when launching from the CLI as well:

• “-prefs” – On version 1.1.4 and newer, this will print out all preferences as NoMAD sees them, including whether or not they are being forced via a configuration profile.
• “-rawLDAP” – This will list all LDAP queries and responses as NoMAD works. You’ll get to see the actual ldapsearch syntax being used and the full LDIF response from the LDAP server.
• “-shares” – This will list all file shares as seen by NoMAD and give you more verbose output specific to the file shares menu.

All of these options can be used together or individually when launching NoMAD from the CLI.

Configurations

The vast majority of issues we see with organizations using NoMAD are due to configuration issues. Most of these configuration issues are in turn caused by creating malformed configuration profiles, scripting defaults instead of using a configuration profile, or managing preference keys that aren’t meant to be managed.

The simplest way to test for this is to pull the configuration and see if the problem persists. If the problem is with the configuration itself, the next easiest step is to attempt to validate the XML, if you’re using a configuration profile.

A good general rule of thumb when dealing with configurations is to manage only as much as you absolutely need to. As an example, you generally shouldn’t have any settings in NoMAD that are set to a blank value.

Network and AD

The next most common problem is with either the network or the AD configuration that’s in use. By now, NoMAD is rather resilient to any network outages and other issues. More common are more “exotic” AD configurations. While we’ve seen a lot of these and have work arounds for most, there are always new ones.

More Troubleshooting Tips

So, you’ve kinda-sorta got it working, but it’s not doing what you want… or it’s just flat out failing. Here’s how to replicate what’s going on manually to find out where things have gone awry.

1. SRV Records

The first thing NoMAD does is attempt to look up your AD Domain Controllers via a DNS lookup for any LDAP SRV records. For the following examples, we’ll be using “company.com” as your AD domain and “server.company.com” as your AD Domain Controller. If you’re playing along at home, swap your real information in for these examples:

dig +short -t SRV _ldap._tcp.company.com

This will query DNS for any LDAP SRV records. If you don’t get any results, this means that you’re a) not able to reach your corporate AD domain, at which point it’s probably a VPN issue or general network issue, or that b) you can’t get any DNS resolution for your domain. Make sure that you’re using the expected DNS servers, or that you can actually reach your internal network.

2. Kerberos Login

Once you’ve gotten some results of the SRV lookup, the next step is to attempt to get a Kerberos ticket with an AD username and password:

kinit user@COMPANY.COM

No news is good news here, but you can test to ensure that it worked by using the klist command, which should show that you have a Kerberos TGT for your domain.

If this doesn’t work, it’s most likely that you are once again unable to reach any of the AD Domain Controllers.

3. LDAP Queries

If you were able to login via Kerberos, you can try looking up information via LDAP.

Use any of the servers that you find via the dig command in the first step and attempt to do an LDAP query against it:

ldapsearch -LLL -Q -H ldap://server.company.com -s base defaultNamingContext

This should return a chunk of text with a defaultNamingContext attribute in it. This lets you know that you can in fact use that username and password to lookup information via LDAP.

If this doesn’t work, you’re probably either not on the internal network, or you may have some funky access rights in AD that will cause further issues.

4. Windows CA Troubleshooting

Listed below are few top tips for working with Windows Certificate Authorities (CA). Much like the rest of NoMAD there isn’t any real magic to this as well. NoMAD will leverage your AD credentials to request a certificate from the CA’s web portal. In order to regress any issues you can manually attempt this process by just using Safari.

• Use NoMAD to ensure you are logged in with your AD user and that you have a valid Kerberos TGT

• Use Safari, as it's Kerberos-aware by default, to connect to the CA web portal. This typically be in the style of ```https://x509.domain.com/certsrv```

• You should be automatically logged in. If you are presented with a security dialog about trusting the CA's SSL cert, this may be where things are going wrong. Import that CA's root cert into your local keychain and trust it. NoMAD won't connect if the web server is untrusted. If you're not automatically logged in, the web portal is most likely not set to use "Windows Authentication" which is just a checkbox in the Microsoft IIS settings. Without this set, the web portal will be asking for a password and not a Kerberos ticket.

• If all of that works, you should be able to request a certificate through the web portal. Note that some earlier versions, i.e. pre-Windows 2008, of the portal leveraged ActiveX in the web page and may not work on a Mac. When you go through this process, you should be able to specify a certificate template to use. You should use that same template name in NoMAD.

Reporting Issues

If you’re a support customer, please use the support email and we’ll get to work on figuring out what’s going on for you. In addition, or if you don’t have a support contract, you can file an issue on the NoMAD GitLab page or hop into the #nomad Slack channel at macadmins.slack.com.

Configuration

NoMAD uses a dictionary of keychain item names and then account names to find the keychain items in the user’s keychain. The account name can use NoMAD’s variable substitution to create the account name since it most likely won’t be just the user’s UPN or shortname. All the standard NoMAD variables work here: <<domain>>, <<fullname>>, <<serial>>, <<shortname>>, <<upn>>, and <<email>>.

In the following keychain item example, the keychain item name is “NoMAD Fake App” and the account name is “joel@nomad.test”:

You can create this dictionary via the defaults command in a few ways. If you know everything all at once, you can create the dictionary inline:
defaults write com.trusourcelabs.NoMAD KeychainItems '{ "App1" = "User1"; "App2" = "User2"; "App3" = "User3"; }';
(Make sure you take care with all of the single and double quotes.)

You can also do this with the -dict and -dict-add flags:

defaults write com.trusourcelabs.NoMAD KeychainItems -dict "App1" "User1"

defaults write com.trusourcelabs.NoMAD KeychainItems -dict-add "App2" "User2"

Troubleshooting

Run NoMAD in verbose mode, and you’ll get lots of logs about what’s going on— so that’s the first place to start. Included in this, you’ll see whether the keychain item was found and if there were any errors in changing it.

You can also set the KeychainItemsDebug preference key, which will have NoMAD update the keychain items every time the user signs in, rather than simply when the password is changed. This should greatly simplify testing variable substitution and other functions.

Keep in mind that not all applications use plain text passwords anymore; many of the cloud services, for instance, will generate a user token and store that in the keychain instead. Thus, use Keychain Access to ensure that the password is actually what you think it is before attempting to have NoMAD manage it.

Still To Come

Currently, this only changes application passwords and not Internet passwords. Look for that in a future update.

Configuring the Window

The default HTML files can be found inside the NoMAD.app bundle. You’ll find a WelcomeSplash.html file in the Resources folder. Changing this file will break the application signing and render NoMAD unusable. However, you can specify a local path to this file with the MenuWelcome preference key. This preference is a String that points to the folder enclosing an index.html page that you’d like to use.

Additionally, you can prevent the window from showing by setting the DontShowWelcome key. This is a boolean value.

This window will not be shown on macOS 10.10 due to WebKit requirements.

Where does it go?

The preference domain is menu.nomad.shares. You can place an xml version of the file in ~/Library/Preferences/menu.nomad.shares.plist for testing purposes, although for long-term use it’s highly recommended to push this out via a configuration profile.

How do you make it?

There are 3 top-level objects in the file.

Note: the use of [ ] around an object types denotes an array of that type of object.

1. Version – This is the version number of the file format. Currently, the only version is 1.

2. HomeMount – This is a dictionary of attributes for scenarios where the user’s home profile should be mounted:

Groups – [String] – Only mount the home for members of these AD groups.
Mount – Bool – Mount automatically or not.
Options – [String] – Array of mount options defined below.

3. Shares – [Dictionary] – An array of dictionaries with each dictionary defining a mount point and associated attributes. The contents of each dictionary are as follows:

AutoMount – Bool – Is the share automatically mounted.
ConnectedOnly – Bool – Is the share only mounted when on the AD domain.
Groups – [String] – An array of AD group names. This share will only auto-mount for members of that group.
LocalMount – String – A local mount point.
Name – String – The name of the share as it will appear in the NoMAD menu item.
Options – [String] – Array of mount options defined below.
URL – String – The actual URL of the mount point in the form of “smb://dc1.nomad.test/Homes”.

Options

First off, huge thanks to @frogor for figuring these out. Note that most of these are probably neither very safe, nor useful. Please use at your own risk. The primary ones that most admins will care about are MNT_RDONLY, MNT_DONTBROWSE and MNT_NOEXEC.

"MNT_RDONLY" - Mounts the share read only
"MNT_SYNCHRONOUS" - All I/O to the file system should be done synchronously.
"MNT_NOEXEC" - Prohibts execution of code from the share
"MNT_NOSUID" - Do not allow set-user-identifier or set-group-identifier bits to take effect.
"MNT_NODEV" - Do not interpret character or block special devices on the file system.
"MNT_UNION" - Causes the namespace to appear as the union of directories of the mounted filesystem with corre-
sponding directories in the underlying filesystem.
"MNT_ASYNC" - All I/O to the file system should be done asynchronously.
"MNT_CPROTECT" -
"MNT_EXPORTED" - Filesystem is exported
"MNT_QUARANTINE" - File system is quarantined
"MNT_LOCAL" - File system is stored locally
"MNT_QUOTA" - Quotas are enabled
"MNT_ROOTFS" - Identifies the root filesystem
"MNT_DOVOLFS" - Filesystem supports volfs (deprecated flag in Mac OS X 10.5)
"MNT_DONTBROWSE" - Does not display the share in the Finder
"MNT_IGNORE_OWNERSHIP" - Ignore ownership information on file system objects
"MNT_AUTOMOUNTED" - Set flags on the mountpoint to indicate that the volume has been mounted by the automounter.
"MNT_JOURNALED" - Mount filesystem journaled
"MNT_NOUSERXATTR" - User extended attributes not allowed
"MNT_DEFWRITE" - Filesystem should defer writes
"MNT_MULTILABEL" - Support for individual labels
"MNT_NOATIME" - Do not update the file access time when reading from a file.


Variable Substitution

For the URLs, you can use variable substitution to allow for custom mounts without having to create even more XML. NoMAD understands <<domain>>, <<fullname>>,<<serial>>,<<shortname>>,<<upn>> and <<email>>.

Using any of these in a URL will swap out that variable for the corresponding value from the users’s AD account.

Viewing the Preference File

This is what you will see if viewing the file via the defaults command:

{ HomeMount = {
Groups = ( "Domain Users" );
Mount = false;
Options = ( );
};
Shares = (
{ AutoMount = false;
ConnectedOnly = true;
Groups = ( "Share Mounter Test" );
LocalMount = "";
Name = "File Server 2";
Options = ( );
URL = "smb://dc2.eng.nomad.test/Files";
},
{ AutoMount = true;
ConnectedOnly = true;
Groups = ( );
LocalMount = "";
Name = "Home Shares";
Options = ( );
URL = "smb://dc1.nomad.test/Homes";
},
);
Version = "1";
}

And here is an XML version of the same:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
     <key>HomeMount</key>
     <dict>
          <key>Groups</key>
          <array>
               <string>All</string>
          </array>
          <key>Mount</key>
          <true/>
          <key>Options</key>
          <array/>
     </dict>
     <key>Shares</key>
     <array>
          <dict>
               <key>AutoMount</key>
               <true/>
               <key>ConnectedOnly</key>
               <true/>
               <key>Groups</key>
               <array/>
               <key>LocalMount</key>
               <string></string>
               <key>Name</key>
               <string>DC1 files</string>
               <key>Options</key>
               <array/>
               <key>URL</key>
               <string>smb://dc1.nomad.test/Files</string>
          </dict>
          <dict>
               <key>AutoMount</key>
               <true/>
               <key>ConnectedOnly</key>
               <true/>
               <key>Groups</key>
               <array/>
               <key>LocalMount</key>
               <string></string>
               <key>Name</key>
               <string>Home Shares</string>
               <key>Options</key>
               <array/>
               <key>URL</key>
               <string>smb://dc1.nomad.test/Homes/&lt;&lt;shortname&gt;&gt;</string>
          </dict>
     </array>
     <key>Version</key>
     <string>1</string>
</dict>
</plist>

While you’re more than welcome to explore and customize NoMAD as much as you desire, these first eight preferences are the best place to start when looking at a new deployment of NoMAD. Detailed information on how to configure these preferences is available on the preferences page.

1. ADDomain – String – This is really the only key you need to have. It determines what your AD domain is and will commonly be in the form of the DNS name of your domain, e.g. nomad.menu.
2. RenewTickets – Boolean – This value determines whether NoMAD will automatically renew Kerberos tickets or not. This is commonly set to “true” as there’s very little reason not to.
3. SecondsToRenew – Integer – Represents the ticket lifespan threshold when NoMAD will renew the ticket. This commonly set to 7200, or 2 hours. If a ticket is valid for less than 2 hours, NoMAD will renew it.
4. LocalPasswordSync – Boolean – This instructs NoMAD to synchronize the AD password to the local account whenever a user logs in or changes their password through NoMAD. This keeps FileVault, the user’s local account, and their keychain all in sync with their AD password.
5. UseKeychain – Boolean – This value tells NoMAD to store the user’s AD password in their keychain. This is commonly set to “true” as a convenience for the user.
6. UPCAlert – Boolean – Setting this to “true” will have NoMAD alert the user when the user’s password was changed outside of NoMAD, such as on another PC or via AD Users and Computers. This helps to keep everything in sync, especially when the Mac is bound to AD. For this to be most effective on bound machines you need #5, #6 and #7 all enabled so that the user’s AD password is in their keychain.
7. GetHelpType – String – This is the method used for the Get Help menu item. It’s either Bomgar, URL or App.
8. GetHelpOptions – String – The URL or Path for GetHelpType (<<serial>>, <<fullname>>, <<shortname>> and <<domain>> are currently supported as substitutions)

No, it doesn’t. NoMAD will work in a very similar way whether you are bound to AD or not. Although we believe being unbound is simpler, we fully realize that there a number of valid reasons why you might still want to bind a Mac to AD.

Can NoMAD update the user’s password?

Yes, NoMAD can. It won’t by default, but you can set a preference key to allow this to happen. Keep in mind that NoMAD can only sync from AD to the local system, and not the other way around.

Is NoMAD free?

NoMAD is an MIT-licensed open source project, and you are free to not only download the application and use it, but to also use the source. If you like the software and need support, please look at our support page where you’ll find a variety of support plans available.

Can NoMAD be customized?

Yes! Almost every function of NoMAD can be customized for you environment. Please see our knowledge base article on all of the preferences and what they do.