README.md 8.96 KB
Newer Older
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
1
# <img src="networkShareMounter.png" alt="drawing" width="90px"/> networkShareMounter
Oliver Kett's avatar
Oliver Kett committed
2

3
In a university, there is a requirement that departments have specific SMB shares on their own network that users should mount. In the same way, in a company - depending on the department or location - there could also be different shares that are to be used. The idea behind the networkShareMounter is that there is a single application that takes care of mounting a list of network shares in an enterprise or university environment. Such a list of shares will be ideally distributed as configuration profiles with an MDM based on workgroups, departments, project-groups etc.
Oliver Kett's avatar
Oliver Kett committed
4

5
Based on the network accessibility, the shares are mounted in the background without any user interaction. Even if a mount fails (e.g. if the share is unreachable), no GUI will be displayed. A Kerberos environment is therefore recommended so that no authentication is required for a mount. Alternatively, the user credentials can also be stored in the user's keychain by manually mounting a share once. So please note that no notification will be displayed if the credantials are invalid or unavailable!  
Gregor Longariva's avatar
Gregor Longariva committed
6

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
7
**Configuration**  
8
Network shares are stored in a NSUserdefaults domain among other configurable aspects of the app. The easiest way to do this is to create a configuration profile and distribute is via MDM. Alternatively, the configuration can also be done manually via the command line. As a tip: to avoid creating a profile for every user, use %USERNAME% which will be replaced with the login name of the current user. See [configuration preferences](#configuration-preferences) in v2 for all available values. 
Oliver Kett's avatar
Oliver Kett committed
9

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
10
**SMBHome**  
11
If the current user has the attribute `SMBHome` defined via LDAP or Active Directory, the user home will also be mounted automatically. This is usually the case when the Mac is bound to an Active Directory and the LDAP attribute `HomeDirectory` is set. You can also set it for a local user if you want: `dscl . create /Users/<yourusername> SMBHome \home.your.domain<yourusername>`.
Oliver Kett's avatar
Oliver Kett committed
12

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
13
**v2 and Legacy?**  
14
Staring with December 2021 there are two different versions of the app: The [background LaunchAgent comamnd line application](#networksharemounter-legacy-the-command-line-app) legacy app (not under active development anymore) and a [menu bar based app](#network-share-mounter-v2) with more configuration options and features for end users. 
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
15
16

## Network Share Mounter (v2)
17
The *Network Share Mounter* app is loosely based on the code of the command line version. It lives in the user's menu bar and is more visible and manageable for the user, as it has the possibility to add some (additional personal) shares to be mounted or the user can decide if the app will be automatically started on login. 
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
18
19

### Configuration preferences
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
20
21
22
For an easier configuration of all the preference keys without creating or modifying a custom Configuration Profile in XML format we provieded a JSON Manifest Schema for Jamf Pro. [Download the manifest file](https://gitlab.rrze.fau.de/faumac/networkShareMounter/-/blob/master/jamf-manifests/Network%20Share%20Mounter.json). 

 The defaults domain for v2 is `de.fau.rrze.NetworkShareMounter`. List with all available values: 
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
23
24
25

| Key                 | Type  | Description            | Default Value | Aviable in version | Required? | Example |
| :------------------ | :---- | :---------------------|:-------------------------------------- | --------------------------------- | ------- | ---- |
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
26
27
| `networkShares`     | Array | Array with all (SMB) network shares. For example configured through a MDM. Note: %USERNAME% will be replaced with the current user's login name.| - | all | - |`smb://filer.your.domain/share`<br />`smb://homefiler.your.domain/%USERNAME%`|
| `customNetworkShares` | Array | Array with all user configured (SMB) network shares. It's not recommend to set this array via MDM | - | all | optional |`smb://myhomefiler.my.domain/share`|
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
28
29
30
31
32
33
34
| `autostart` | Boolean | If set, the app will be launched on user-login | false | >=2.0.0 | optional ||
| `canQuit` | Boolean | If set, the user can quit the app | true | >=2.0.0 | optional ||
| `canChangeAutostart` | Boolean | If set to false, the user can not change the Autostart option | true | >=2.0.0 | optional ||
| `unmountOnExit` | Boolean | If set to false the shares will be mounted after quitting the app | true | >=2.0.0 | optional ||
| `location` | String | Path where network shares will be mounted. Leave blank for the default value (highly recommended) | - | >=2.1.0 | optional | `/Volumes` |
| `cleanupLocationDirectory` | Boolean | If set to true, the mount location will be cleaned up from obstructing files and directories. Use with caution if the location directory is not the default!| false | >=2.1.0 | - | `false` |
| `helpURL` | String | Configure a help URL to help users interact with the application | - | >=2.0.0 | optional |https://www.anleitungen.rrze.fau.de/betriebssysteme/apple-macos-und-ios/macos/#networksharemounter|
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
35
36

#### Important note for `location` and `cleanupLocationDirectory` values
Gregor Longariva's avatar
Gregor Longariva committed
37
38
39
If `location` is left empty (or is not defined), a directory is created in a subdirectory of the user's home where the network drives will be mounted. Since this directory always contains only mounted network shares, there is a routine that cleans up this directory and deletes unnecessary files and directories.    
If another directory is used to mount the network drives (like `location` set to, for example, `/Volumes`) **it is strongly recommended** to disable the cleanup routine by setting `cleanupLocationDirectory` to `false`.

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
40
41
42
### Screenshots
Screenshots of our Network Share Mounter app. On the left the menu bar icon with the mount, unmount and quit options. On the right the configuration window with the custom network share list:

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
43
<img src="networkShareMounterv2Screenshot.png" />  
Gregor Longariva's avatar
Gregor Longariva committed
44

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
45
----  
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
46

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
47
48
49
50
51
52
## networkShareMounter Legacy (the command line app)

The legacy networkShareMounter is started by a [LaunchAgent](https://gitlab.rrze.fau.de/faumac/networkShareMounter/-/blob/master/networkShareMounter/de.uni-erlangen.rrze.networkShareMounter.plist) at every network change (for automatic remounting) and when a user logs in. This process is done in the background, without any user interaction. 

### How to configure the command line app

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
53
The defaults domain for our [pre-built package](https://gitlab.rrze.fau.de/faumac/networkShareMounter/-/releases) is `de.uni-erlangen.rrze.networkShareMounter`. If you want to distribute the plist with a configuration profile you have to do it with the payload `com.apple.ManagedClient.preferences` like this:
Oliver Kett's avatar
Oliver Kett committed
54
55

```xml
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
56
57
58
59
60
61
<?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>networkShares</key>
	<array>
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
62
		<string>smb://home.your.domain/%USERNAME%</string>
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
63
64
65
66
67
		<string>smb://filer1.your.domain/share</string>
		<string>smb://filer2.your.domain/another share/foobar</string>
	</array>
</dict>
</plist>
Oliver Kett's avatar
Oliver Kett committed
68
69
```

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
70
[Download example Configuration Profile](https://gitlab.rrze.fau.de/faumac/networkShareMounter/-/blob/master/jamf-manifests/networkShareMounter%20Legacy.mobileconfig).
Gregor Longariva's avatar
Gregor Longariva committed
71

Gregor Longariva's avatar
typo    
Gregor Longariva committed
72
If you want to configure shares manually, you can use this command:
Gregor Longariva's avatar
Gregor Longariva committed
73

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
74
75
76
```bash
defaults write de.uni-erlangen.rrze.networkShareMounter networkShares -array "smb://filer.your.domain/share" "smb://filer2.your.domain/home/Another Share/foobar" "smb://home.your.domain/%USERNAME%"
```
Oliver Kett's avatar
Oliver Kett committed
77

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
78
79
```bash
defaults write de.uni-erlangen.rrze.networkShareMounter customNetworkShares -array "smb://private.filer.home/share"
Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
80
```
Gregor Longariva's avatar
Gregor Longariva committed
81

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
82
83
84
85
86
### Optional paramater and options

* With the optional array  `customNetworkShares`  users can add own network shares to the configuration. See manually confiugration above for detauls.
* There is an optional parameter `--openMountDir` which opens a new finder window of the networkShareMounter mount directory. (e.g. "\~/Network shares" or "\~/Netzlaufwerke")
* If you want to change the installation directory, go to **Build Settings** > **Deployment** > **Installation Directory**. But keep in mind that you also have to change the path of the LaunchAgent (command line version). 
Gregor Longariva's avatar
Gregor Longariva committed
87

Dominik Schuppenhauer's avatar
Dominik Schuppenhauer committed
88
89
90
91
92
93
## FAQ
### 1) Jamf recon stuck with configured Network Share Mounter app
This is probably due the innventory collection configuration "Include home directory sizes" in Jamf (Pro). Both Network Share Mounter versions, v2 and legacy, mounting the shares in the users home (~/Network Shares). If the option is now enabled, Jamf will also try to collect the size of the network share mounter mounts and the process get stuck.

To resolve this behaviour, go to **Settings > Computer Management - Management Framework > Inventory Collection** and disable the option **Include home directory sizes**.

Gregor Longariva's avatar
Gregor Longariva committed
94
## Contact
95
96
Feel free to contact us for ideas, enhancements or bug reports at the [service desk address](mailto:rrze-gitlab+faumac-networksharemounter-506-issue-@fau.de).    
For general questions you can write directly to the team at [rrze-mac@fau.de](mailto:rrze-mac@fau.de).
Gregor Longariva's avatar
Gregor Longariva committed
97
98


Gregor Longariva's avatar
Gregor Longariva committed
99
`Developed with ❤️ by your FAUmac team`
Gregor Longariva's avatar
Gregor Longariva committed
100