A few weeks back I introduced a new tool: utiluti, which sets default apps for url schemes and file types.
Not standing still, I have updated the tool with new verbs to list url schemes and file types that a given app can handle, as well as inspect and set default apps set for specific files.
You can see the Readme and download the latest release on the GitHub repo.
A while back I wrote a post on the Jamf Tech Thoughts blog about managing the default browser on macOS. In that post I introduced a script using JXA to set the default application for a given url scheme. (like http, mailto, ssh etc.) The beauty of using JXA/osascript is that it doesn’t require the installation of an extra tool.
However, there was a follow-up comment asking about default apps for file types, i.e. which app will open PDF files or files with the .sh file extension. Unfortunately, Apple has not bridged those AppKit APIs to AppleScript/JXA, which means it is not possible to use them in a script without dependencies.
Back then, I started working on a command line tool which uses those APIs. I didn’t really plan to publish it, since there were established tools, like duti, cdef and SwiftDefaultApp that provided the functionality. It was a chance to experiment and learn more about Swift Argument Parser. Then life and work happened and other projects required more attention.
A recent discussion on the Mac Admins Slack reminded me of this. Also, none of the above mentioned tools have been updated in the past years. As far as I can tell, none of them have been compiled for the Apple silicon platform. They don’t provide installation pkgs either, which complicates their distribution in a managed deployment.
So, I dusted off the project, cleaned it up a bit, and added a ReadMe file and a signed and notarized installation pkg. The tool is called utiluti (I am a bit proud of that name).
You can use utiluti to set the default app for an url scheme:
$ utiluti url set mailto com.microsoft.Outlook set com.microsoft.Outlook for mailto
or to set the default app to open a uniform type identifier (UTI):
$ utiluti type set public.plain-text com.barebones.bbedit set com.barebones.bbedit for public.plain-text
There are bunch of other options, you can read the details in the ReadMe or in the command line with utiluti help.
The functionality is quite basic, but please provide feedback if there are features you’d like to have added.
When building tools in Swift, I usually start with a command line tool. This allows me to ignore the complexity of creating a user interface while figuring out the underlying APIs and data models.
Technically, command line tools have a user interface, as well. They print output to pipes, standard out or standard error for data, progress, status or other information. They should provide information using the exit status. They take input from standard in, pipes, environment variables, or from command line arguments.
While there are many subtleties to consider with all of these, these “interfaces” are still less complex to handle than a full user interface built with AppKit, UIKit or SwiftUI.
Swift provides the functionality to deal with files, outputs, pipes with APIs. This post will not cover those. This post will focus on getting arguments from the command line.
Note: this tutorial was written using Swift 5.10, Xcode 15.4, swift-argument-parser 1.5 on macOS 14.6.1. The details and user interfaces may change with different versions, but the fundamentals should remain.
The built-in way to get the arguments for your process is with CommandLine.arguments which returns an array of String objects. CommandLine.arguments is quite basic, but can be suitable for simple use cases.
Create a project directory named CLArgs and use swift package init to create a swift package to build an executable:
> mkdir CLArgs
> cd CLArgs
> swift package init --type executableThis will create a skeleton project, you will find a basic “Hello, world” code in Sources/main.swift. Replace the print statement there with:
import Foundation
let arguments = CommandLine.arguments.dropFirst()
guard let name = arguments.first
else {
print("command requires an argument!")
exit(1)
}
print("Hello, \(name)")Note: You can use your favorite text editor or IDE to edit SPM projects. You can also use Xcode. When you run xed . in the Swift package directory, Xcode will open the Swift package in a project view. You can edit, build and run the package in Xcode or use Xcode for editing and build and run it from the command line.
In terminal, build and run the project with
> swift run CLArgs ArminThis tells the swift to build the CLArgs target defined in Package.swift and run it with the argument Armin. You should see this output:
> swift run CLArgs Armin
Building for debugging...
[1/1] Write swift-version-39B54973F684ADAB.txt
Build of product 'CLArgs' complete! (0.11s)
Hello, ArminLet’s look at the code in detail.
let arguments = CommandLine.arguments.dropFirst()CommandLine.arguments returns an array of strings. By convention, the first argument (arguments[0]) contains the path to the executable. In most situations, you will not be interested in this first argument. One straightforward way to deal with this is to ‘drop’ the first element of the array right away.
guard let name = arguments.first
else {
print("command requires an argument!")
exit(1)
}We get the first element of the arguments array. Additional arguments are simply ignored. When no arguments are provided, this will return nil and guard statement will trigger, where we print an error message and exit the code with a non-zero value, signaling a failure.
print("Hello, \(name)")The actual point of this sample code: print a greeting with the name.
In this simplest of examples, we spend a majority of the code on preparing the arguments and verifying that they meet our requirements.
CommandLine.arguments will serve you well for simple needs and quick command line tools. However, you will quickly notice that a robust command line tool needs to verify the existence of certain arguments, whether the value matches certain criteria, and print error messages and usage directions when the arguments don’t match the expectations. Many command line tools also have flags and options with short and long forms that need to be processed.
This turns into a lot of code very quickly.
Enter Swift Argument Parser. A package that provides “straightforward, type-safe argument parsing for Swift.”
You could modify the Package.swift file in our CLArgs project to import Swift Argument Parser but there is an even easier way to start. Back out of the CLArgs project directory and create a new one:
> cd ..
> mkdir SwiftArg
> cd SwiftArg
> swift package init --type toolWhen you inspect the Package.swift file in this new project, you will see that it is already linked to the Swift Argument Parser package. Sources/SwiftArgs.swift contains another “Hello, world” template code, but using Swift Argument Parser.
import ArgumentParser
@main
struct SwiftArgs: ParsableCommand {
mutating func run() throws {
print("Hello, world!")
}
}The struct here implements the ParsableCommand protocol which allows us to use all the nice functionality from the ArgumentParser library. It is also marked with the @main tag, which tells the compiler to run the main() function in this when the binary is launched. The main() function is implemented by ParsableCommand which, well, parses the arguments and then launches the run() function.
You can open and edit Swift Package Manager projects in Xcode with the xed . command. Recent Xcode versions know how to work with SPM projects without needing to create an Xcode project file. Xcode will use the configurations in the Package.swift file. This is useful when you like to work in Xcode, but want the project to remain transferable to other editors or IDEs.
There is a weird quirk. When you build and/or run the project from within Xcode it will use the default Xcode build directory (default is ~/Library/Developer/Xcode/DerivedData/). This is different from the location that the swift build or swift run commands in Terminal use (.build in the package directory). This can lead to longer build times and confusion.
You can also use swift-argument-parser and other packages within Xcode projects. This can be necessary if you are building the command line as a target within a larger Xcode project. Maybe you want to use some of Xcode’s advanced features for managing projects, like build phases and Archives. Or maybe you just prefer working in Xcode.
To create a command line with ArgumentParser in Xcode, create a new Project and select the ‘Command Line Tool’ template for macOS. Once the new project is created, select ‘Add Package Dependencies…’ from the File menu. Locate ‘swift-argument-parser’ in the ‘Apple Swift Packages’ collection or just enter the URL in the search field and click ‘Add Package…’ (twice)
Then, you have to delete the main.swift file from the template and create a new SwiftArgs.swift with this code:
import Foundation
import ArgumentParser
@main
struct SwiftArgs: ParsableCommand {
mutating func run() throws {
print("Hello, world!")
}
}This is the same as the template code created with the swift package init --type tool from above.
When testing and running the command line tool in Xcode will will want to pass arguments into the binary. You can do so by editing the scheme. Choose Product > Scheme > Edit Scheme… from the menu or click on the target icon (the one with the command line icon in the center of the menu bar) and select Edit Scheme… Make sure you are on the ‘Run’ section in that dialog and select the ‘Arguments’ tab. Here you can add, remove, enable or disable the arguments that Xcode passes into your tool when you run it from Xcode.
Continually changing the arguments in the scheme editor can be tedious. You can also use ‘Show Build Folder in Finder’ from the ‘Product’ menu, open the Products/Debug folder in Terminal by dragging that folder on to the Terminal icon in the Dock and run the built command from there with ./SwiftArgs
Whichever way you prefer to create and work with your project, the rest of this tutorial will work the same way.
Right now, we are just running print("Hello, world!"), which is quite underwhelming. Let’s step this up just a little bit:
@main
struct SwiftArgs: ParsableCommand
@Argument var name: String
func run() {
print("Hello, \(name)")
}
}First we create a property called name of type Stringwith the @Argument property wrapper. This tells the ArgumentParser library, that we want this variable filled with an argument from the command line. When the run() function is called, we can “just use” the name property, like any other Swift property.
When you run this, something interesting happens: we get an error!
> swift run SwiftArgs
Error: Missing expected argument '<name>'
USAGE: swift-args <name>
ARGUMENTS:
<name>
OPTIONS:
-h, --help Show help information.When you check the exit code of the command with echo $? you see it return an error code of 64. This means it was missing arguments or got malformed arguments. As should be good practice for command line tools, our tool did print a help message, describing what it was expecting. Here we see that our SwiftArgs command expects a single argument giving a name.
Run the command again, but with an argument:
> swift run SwiftArgs Armin
Hello, ArminNow everything works as expected. When our tool launches, ArgumentParser grabs the argument, places it in our name property and executes the run() function in our struct that implements ParsableCommand. Since ArgumentParser errors out with the help message, when an argument is missing or too many arguments are present, we can be certain that the name variable is populated when our code runs.
There is a small detail that is bugging me, though. The help message generated by ArgumentParser deduced that the name of binary should be swift-args instead of SwiftArgs, but the binary name is SwiftArgs, which is the name of the directory we initialized the project in. This is because of different naming standards for Swift types and command line tools. You can change the name of the executable created in the Package.swift file in line 15 under .executableTarget.
We could change the name to something completely different here, say apdemo for ‘Argument Parser Demo. When you apply that change inPackage.swift` it changes the name of the binary, but the auto-generated help message does not pick that up. It still use the auto-generated name.
> swift run apdemo --help
USAGE: swift-args <name>
ARGUMENTS:
<name>
OPTIONS:
-h, --help Show help information.(Isn’t it neat that ArgumentParser automatically implements --help and -h flags?)
We could change the name of our struct, which will work in simple situations. But you will have a situation where the struct name will not match what you want for the executable name. There is a way to tell ArgumentParser exactly what we want, though.
Insert this code below the struct SwiftArgs line and above the @Argument:
static let configuration = CommandConfiguration(
commandName: "apdemo"
)When you now look at the generated help again, the command name matches:
OVERVIEW: apdemo - swift-argument-parser tutorial tool
USAGE: apdemo <name>
ARGUMENTS:
<name>
OPTIONS:
-h, --help Show help information.There is more information we can provide in the command configuration. Extend the CommandConfiguration initializer like this:
static let configuration = CommandConfiguration(
commandName: "apdemo",
abstract: "apdemo - swift-argument-parser tutorial tool",
version: "0.1"
)and run the command to get the help message again.
OVERVIEW: apdemo - swift-argument-parser tutorial tool
USAGE: apdemo <name>
ARGUMENTS:
<name>
OPTIONS:
--version Show the version.
-h, --help Show help information.The abstract appears as an ‘overview’ above the help message and we now see a new option --version. When you run the tool with that option, you will not be surprised to see the 0.1 provided in the configuration, but it is useful nonetheless.
There are more fields you can provide in the CommandConfiguration: discussion allows you to provide a long form description of the command. usage allows you to override the auto-generated usage text. There are some more that we will explore later.
You can add more @Arguments and they will be filled in order from the arguments provided at the command line. Add another property with the @Argument wrapper:
@Argument var name: String
@Argument var age: Int
func run() {
print("Hello, \(name)!")
print("You are \(age) years old.")
}When you run the tool without any arguments, you can inspect the updated help message. The usage and arguments area now shows both expected arguments. When you run the tool with a single argument, you get an abbreviated help, showing only the missing argument. When you provide a name and a number as command line arguments, everything works as expected.
But what if you provide two strings?
> swift run apdemo Armin lalala
Error: The value 'lalala' is invalid for '<age>'
Help: <age>
Usage: apdemo <name> <age>
See 'apdemo --help' for more information.We declared the age property as an Int, so ArgumentParser expects an integer number for the second argument. When the second argument cannot be parsed into an integer, it shows the error.
Change the type of the age property to a double and run it again with a decimal for the age.
name and age might be enough to tell a user of your command line tool what to enter. But I think we should provide a bit more explanation. You can attach a help message to the argument:
@Argument(help: "a name")
var name: String
@Argument(help: "age (integer number)")
var age: IntI have broken the property declarations into two lines each for clarity and changed the age back to an Int for simplicity. The help messages will appear next to the argument names in the long and short help messages.
We have just started to scratch the surface of what swift-argument-parser can do for us. In the next part, we will cover options and flags.
In my last post introducing desktoppr 0.5, I said that a Mac admin could build a customized pkg with a customized LaunchAgent property list, that would run desktoppr manage at login and every few hours in the background to re-set the wallpaper when the configuration profile is updated.
I admit I glossed over the process of building a package that installs and launches a LaunchAgent (or LaunchDaemon). Since that is not a trivial configuration, I will describe the details in this post.
On macOS, launchd is the system-wide process that controls and launches every other process running on the system. When you look at the hierarchical process list in Activity Monitor, you will always see launchd running with the process ID 1 as the single child process of kernel_task and all other processes are a child of launchd.
More practically, users and admins can use launchd to control processes that need to be available at all times or be launched in certain intervals or at certain events.
launchd has two types of processes: LaunchDaemons and LaunchAgents. Since the terms daemons (or demons) and agents do not have clear definitions outside of launchd, a bit of explanation is required.
LaunchDaemons are processes that run with system privileges (“as root”). Processes that belong to your management system and security suites may need to run periodically or on certain events in the background and require root level access to the system to do their jobs. Other processes or services need to listen for incoming network traffic on privileged ports.
Note that background process are often called ‘agents’ regardless of whether they run with root privileges or as a user. The launchd terminology is more precise here.
Apple has done a lot of work over the past few year to provide Endpoint Security or Network Extension frameworks that mitigate the need for third party root daemons, but there are still relevant use cases, especially when you are a managing Macs.
A LaunchDaemon is configured by providing a property list file in /Library/LaunchDaemons. This configuration plist will be automatically loaded at reboot, or can be loaded using the launchctl command.
LaunchAgents are processes that run with user privileges. Generally, if something needs to read or write to anything in the user home folder, it should be a LaunchAgent. Over the recent years, Apple has put restrictions on what data process can access in user space, which has made LaunchAgents more of a pain to manage, but they still have their use cases.
A LaunchAgent is configured by providing a property list file in /Library/LaunchAgents on the system level or in ~/Library/LaunchAgents in a user’s home folder. Configuration property lists that are in a user home folder, will only run for that user, while LaunchAgents that are configured in the system wide /Library/LaunchAgents will be loaded for all users on the system.
A LaunchAgent configuration plist will be automatically loaded at login, or can be loaded using the launchctl command.
Since desktoppr affects a user setting (the desktop/wallpaper), it has to run as the user, so we need to build and install a LaunchAgent. Creating and installing a LaunchDaemon is pretty much the same process, though.
To build an installation package to install and run a LaunchAgent or LaunchDaemon, you need three ingredients:
For desktoppr, we already have the binary (downloadable as a zip from the project release page) and a sample configuration property list file.
The sample launchd configuration looks like this:
<?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>Label</key>
<string>com.scriptingosx.desktopprmanage</string>
<key>ProgramArguments</key>
<array>
<string>/usr/local/bin/desktoppr</string>
<string>manage</string>
</array>
<key>RunAtLoad</key>
<true/>
<key>StartInterval</key>
<integer>10800</integer>
</dict>
</plist>The label is required and is used to uniquely identify the LaunchAgent or Daemon with launchd and the launchctl command. Reverse domain notification is common. The filename of the configuration property list should match the label.
The ProgramArguments key provides an array with the command and arguments that will be launched. The first item in the array should provide the full path to the binary or script. Then you provide arguments, one string item per argument. Since the individual arguments are separated by the string tags, you do not need to escape spaces or other special characters in the arguments.
It is worth noting that launchd will launch the binary or script directly, so syntax and substitutions that are done in shells will not work. This includes variable and command substitution like $HOME, $USER, or $(date) as well as pipes and output redirection. You get a single command with a list of static arguments. (You can use the StandardOutPath and StandardErrorPath keys in the launchd config plist to redirect output.)
For the desktoppr LaunchAgent, that suits us just fine, as we are only passing the manage argument which tells desktoppr to get the details from a configuration profile (sample here).
The next key, RunAtLoad tells launchd, to run the binary with the arguments immediately when the configuration file is loaded. Since configuration files in /Library/LaunchAgents and ~/Library/LaunchAgents are automatically loaded when a user logs in, this generally means desktoppr manage will be run when a user logs in, which suits us well.
The last key StartInterval tells launchd to re-launch the process after a certain time (given in seconds, the 10800 seconds in our sample file translate to three hours). Should the system be sleeping at the time, it will not run the LaunchAgent at that time, or when the system wakes up, but wait until the next interval period comes around.
There are other keys that control when the process gets launched, such as StartCalendarInterval or WatchPath. You can read details in the man page for launchd.plist or on the excellent launchd.info page. There are also apps, like Peter Borg’s Lingon that provide a user interface for creating these plist files.
Move or copy the plist file into the correct folder. The plist files in /Library/LaunchDaemons and /Library/LaunchAgents must be owned by root. They must not be writable by group or other. The file mode 644 (rw-r--r--) is recommended. Similarly, the binary or script needs to be owned by root and cannot be writable by group or other. The file mode 755 (rwxr-xr-x) is recommended. Wrong file privileges will result in a Load/Bootstrap failed: 5: Input/output error.
Make sure that the binary or script does not have a quarantine flag attached. You can check with ls -al@ or xattr -p com.apple.quarantine /path/to/file and remove a quarantine flag with xattr -d com.apple.quarantine /path/to/file. When the binary or script has the quarantine flag, the configuration file will load fine but the actual execution will fail quietly.
The easiest way to load a LaunchDaemon is to restart the Mac. The easiest way to load a LaunchAgent is to log out and login. This is usually not practical.
The launchctl command manages LaunchDaemons and LaunchAgents and we can use this to load LaunchAgents and LaunchDaemons on demand.
To load our desktoppr agent, use
> launchctl load /Library/LaunchAgents/com.scriptingosx.desktopprmanage.plistPeople are already readying their pitchforks here. “Hold on,” they say. “Apple has marked load and unload as ‘legacy.’ You shouldn’t use them!”
While it is true that load and unload (and a bunch of other commands) are labeled as ‘legacy’ in the launchctl man page, this does not mean they are deprecated and should be avoided. The difference between the legacy and the ‘new’ commands is that the legacy commands pick up whether a process should be run in user or root context (the ‘target domain’) from the context that launchctl runs in, whereas the new bootstrap and bootout commands need the target domain to be stated explicitly.
This makes the modern commands more precise, but often more wordy to use. You will see that the legacy commands are simpler to use in the interactive terminal, while the ‘modern’ commands are more useful in scripts. The equivalent ‘modern’ command is:
> launchctl bootstrap gui/501 /Library/LaunchAgents/com.scriptingosx.desktopprmanage.plistwhere 501 is the user ID for your user account. This is 501 by default for the first user on on a macOS system, but you should verify what your account’s user ID actually is with id -u.
See what I mean with “more wordy to use”? That doesn’t mean they are bad or should be avoided, but that we can be picky about when to use which format. You could argue that using the modern commands throughout would be more consistent, but you still find the ‘legacy’ command is lots of documentation, so I feel a Mac admin needs to be aware of both.
Note: the ‘modern’ commands were introduced in OS X Yosemite 10.10 in 2014.
To load a LaunchDaemon, you need to run launchctl with root privileges. In the interactive shell, that means with sudo:
> sudo launchctl load /Library/LaunchDaemons/com.example.daemon.plistor
> sudo launchctl bootstrap system/ /Library/LaunchDaemons/com.example.daemon.plistTo stop a LaunchAgent from being launched going forward, unload the configuration:
> launchctl unload /Library/LaunchAgents/com.scriptingosx.desktopprmanage.plistor
> launchctl bootout gui/501/com.scriptingosx.desktopprmanageThe bootout command uses the label instead of the file path.
Note: I will be showing how to build and installer package for our LaunchAgent using command line tools. These instructions should have all the information you need, even if you prefer using apps such as Whitebox Packages or Composer.
If you are not comfortable with using Terminal on macOS yet, please consider my book “macOS Terminal and Shell.” If you want to learn more about building installation packages, consider my book “Packaging for Apple Administrators.”
Download the zip file for desktoppr from the releases page. Download the sample launchd property list file and modify the launch criteria (StartInterval or StartCalendarInterval) to your requirements.
Open Terminal, change directory to a location where you want to create the project directory and create a project directory:
> mkdir DesktopprManagePkg
> cd DesktopprManagePkgThen create a payload and a scripts directory in this project folder:
> mkdir payload
> mkdir scriptsUnzip the desktoppr binary from the downloaded zip archive into the right folder hierarchy in the payload folder:
> mkdir -p payload/usr/local/bin/
> ditto -x -k ~/Downloads/desktoppr-0.5-218.zip payload/usr/local/bin/Remove the quarantine flag from the expanded desktoppr binary and test it by getting the version and the current wallpaper/desktop picture:
> xattr -d com.apple.quarantine payload/usr/local/bin/desktoppr
> payload/usr/local/bin/desktoppr version
0.5
> payload/usr/local/bin/desktoppr
/System/Library/CoreServices/DefaultDesktop.heicCreate the /Library/LaunchAgents directory in the payload and copy or move the LaunchAgent configuration plist there:
> mkdir -p payload/Library/LaunchAgents/
> cp ~/Downloads/com.scriptingosx.desktopprmanage.plist payload/Library/LaunchAgents/When the installation package runs, the files in the payload will be moved to the respective locations on the target drive. The pkgbuild tool will set the owner of the files to root when building the package, but we should verify that the file mode is correct:
> stat -f %Sp payload/usr/local/bin/desktoppr
-rwxr-xr-x
> stat -f %Sp payload/Library/LaunchAgents/com.scriptingosx.desktopprmanage.plist
-rw-r--r--If the privileges don’t match the desired mode, set them with chmod
> chmod 755 payload/usr/local/bin/desktoppr
> chmod 644 payload/Library/LaunchAgents/com.scriptingosx.desktopprmanage.plistand run the stat commands from above again to verify.
If you built the installer package now, it will install the files in the right locations and the LaunchAgent will load and run desktoppr manage on next login. This will set the desktop/wallpaper according to the information in the configuration profile. You should install and update the configuration profile using your management system.
However, as I said earlier, requiring or waiting for a logout or reboot is not ideal, we would like to have the LaunchAgent load immediately when the package is installed. We can achieve this by adding a postinstall script to the installation package. This script will be executed after the payload files have been installed.
With your favored text editor, create a file named postinstall (no file extension) with this content in the scripts sub directory.
#!/bin/sh
export PATH=/usr/bin:/bin:/usr/sbin:/sbin
label="com.scriptingosx.desktopprmanage"
launchdPlist="/Library/LaunchAgents/${label}.plist"
# do not load when target volume ($3) is not current startup volume
if [ "$3" != "/" ]; then
echo "not installing on startup volume, exiting"
exit 0
fi
# for LaunchAgent, check if user is logged in
# see https://scriptingosx.com/2019/09/get-current-user-in-shell-scripts-on-macos/
currentUser=$(echo "show State:/Users/ConsoleUser" | scutil | awk '/Name :/ { print $3 }')
# don't load at loginwindow
if [ "$currentUser" = "loginwindow" ] || [ "$currentUser" = "_mbsetupuser" ]; then
echo "no user logged in, exiting"
exit 0
fi
uid=$(id -u "$currentUser")
echo "loading $label"
launchctl bootstrap "gui/$uid" "$launchdPlist"Set the proper file privileges on the postinstall file with
> chmod 755 scripts/postinstallFirst the script sets the PATH. Then some variables for the label and bath to the label. You can change these to adapt the script to other LaunchAgents or LaunchDaemons.
Then the scripts checks the $3 argument. The installer system passes the target volume to the postinstall script in this argument. While it is a not common in deployment workflows any more, you can still install a pkg on a target volume that is not the current boot volume “/“. We remain safe with our script and check for that possibility, and exit without loading the agent.
LaunchAgents have to be loaded or bootstrapped into the current user’s context. The script gets the current user and checks whether the system might be sitting at the login window. We exit without loading if the system is at the login window or if the current user is _mbsetupuser which means the package is being installed while the system is sitting at Setup Assistant during first setup. Now that the LaunchAgent plist is in place, it will be loaded the first time the user logs in.
When there is a user logged in, we bootstrap the LaunchAgent right away. This is where the modern launchctl syntax shows its advantages. With the legacy commands, this would be:
launchctl asuser "$uid" launchctl load "$launchdPlist"When you load a LaunchDaemon in a postinstall, the script is much simpler, as you don’t need to check for a current user. You can directly load the daemon into the system target domain:
launchctl bootstrap system/ "$launchdPlist"When you are updating existing software with a package, you have to consider the situation where a LaunchAgent or LaunchDaemon is already running. In this case, we should unload before the installation. We can add a preinstall script (also no file extension) to the scripts folder that will be run before the payload is installed. This closely parallels the postinstall script.
#!/bin/sh
export PATH=/usr/bin:/bin:/usr/sbin:/sbin
label="com.scriptingosx.desktopprmanage"
launchdPlist="/Library/LaunchAgents/${label}.plist"
# do not unload when target volume ($3) is not current startup volume
if [ "$3" != "/" ]; then
echo "not installing on startup volume, exiting"
exit 0
fi
if ! launchctl list | grep -q "$label"; then
echo "$label not loaded, exiting"
exit 0
fi
# for LaunchAgent, check if user is logged in
# see https://scriptingosx.com/2019/09/get-current-user-in-shell-scripts-on-macos/
currentUser=$(echo "show State:/Users/ConsoleUser" | scutil | awk '/Name :/ { print $3 }')
# don't unload at loginwindow or Setup Assistant
if [ "$currentUser" = "loginwindow" ] || [ "$currentUser" = "_mbsetupuser" ]; then
echo "no user logged in, exiting"
exit 0
fi
uid=$(id -u "$currentUser")
echo "loading $label"
launchctl bootout "gui/$uid" "$launchdPlist"Again, set the proper file privileges on the preinstall file with
> chmod 755 scripts/preinstallThere is one extra step compared to the postinstall script. The preinstall uses launchctl list to check if the launchd configuration is loaded, before attempting to unload it.
Now we get to put everything together. You can use pkgbuild to build an installer package:
> pkgbuild --root payload/ --scripts scripts/ --version 1 --identifier com.scriptingosx.desktopprmanage --install-location / DesktopprManage-1.pkg
pkgbuild: Inferring bundle components from contents of payload/
pkgbuild: Adding top-level preinstall script
pkgbuild: Adding top-level postinstall script
pkgbuild: Wrote package to DesktopprManage-1.pkgThis works well, but it is difficult to memorize all the proper arguments for the pkgbuild command. If you forget or misconfigure one of them it will either fail outright or lead to a pkg installer file with unwanted behavior. I prefer to put the command in a script. Create a script file buildDesktopprManages.sh at the top of your project directory with these contents:
#!/bin/sh
export PATH=/usr/bin:/bin:/usr/sbin:/sbin
pkgname="DesktopprManage"
version="1.1"
identifier="com.scriptingosx.${pkgname}"
install_location="/"
minOSVersion="10.13"
# determine enclosing folder
projectfolder=$(dirname "$0")
# build the component package
pkgbuild --root "${projectfolder}/payload" \
--identifier "${identifier}" \
--version "${version}" \
--ownership recommended \
--install-location "${install_location}" \
--scripts "${projectfolder}/scripts" \
--min-os-version "${minOSVersion}" \
--compression latest \
"${pkgname}-${version}.pkg"This way, you do not have to memorize the pkgbuild command and its arguments and it is easier to modify parameters such as the version. Remember to change the version as you build newer versions of this package going forward!
Some management systems deploy a pkg file using certain MDM commands. Then you need a signed distribution package instead of a simple component pkg file. (You can learn more about the different types of packages in this blog post or this MacDevOps YVR presentation. Building a sign distribution pkg is somewhat more involved. I have a template script for that in the repo.
As I said, building a LaunchAgent for desktoppr manage is not trivial. However, building LaunchAgents and LaunchDaemons and proper installer pkgs to deploy them is an important skill for Mac admins.
There are some other tools available, such as outset, or your management system might have options to run scripts at certain triggers. But in general, I recommend to understand the underlying processes and technologies before using tools, even when the tools are great and a good fit for the task at hand.
You can use this process of building a LaunchAgent and installer pkg for desktoppr as a template for your own scripts and projects. You can find all the files in the desktoppr repo example directory.
Earlier this year, I released a beta version of desktoppr 0.5 which added an option to control the tool using a configuration profile. You can read all the details of how I built out this workflow in this blog post.
I have not received any feedback on it, which can mean two things: either it is working just fine or people simply aren’t aware of the beta. I guess both could be true at the same time here?
The new release is now available in the desktoppr repo. Nothing has changed compared to the 0.5beta except the version number and updated documentation.
desktoppr manageThe new manage verb allows a Mac Admin to set the wallpaper using data in a configuration profile. Together with the new option to download an image file for the wallpaper from an URL, this removes the requirement of updating two or more packages when you want to update the wallpaper on managed devices.
To use the new manage option, you need three pieces
desktoppr installation pkg from the repodesktoppr manageThe LaunchAgent plist file controls when desktoppr will run.
The sample LaunchAgent file has both the RunAtLoad key and a StartInterval key. This means that desktoppr will run when the LaunchAgent loads and repeatedly after the time set in the StartInterval (in seconds, the sample file has 10800, so every three hours, as long as the system is awake).
The desktoppr profile provides a setOnlyOnce key which stops desktoppr from re-setting the same wallpaper over and over again. This way we can run desktoppr frequently, but it will only reset the wallpaper when the picture key in the profile has changed.
Build a pkg to install the LaunchAgent with your preferred frequency (or none) in /Library/LaunchAgents and deploy that together with the desktoppr pkg.
Since macOS Ventura, managed binaries and scripts launched by a LaunchAgent or Daemon should be pre-approved with a configuration profile from the management system, so that the user gets less dialogs about them and cannot disable them. Since desktoppr is a signed binary, this is quite straightforward and the sample configuration profile already contains the com.apple.servicemanagement section.
The second payload in the sample profile contains the settings. The only one that is required is the picture key which contains either a path to a local image file for the wallpaper, or a URL to an image file. Using a hosted file allows you to provide a custom branded wallpaper and change it without needing to deploy files to the client using more custom pkgs.
When you are not using a local file, you can (and probably should) provide a sha256 key with a checksum of the image file. This should protect from attempt to inject something malicious by hi-jacking the download URL. You can generate a sha256 sum for the image file with shasum -a 256 <path/to/file>.
The setOnlyOnce key controls whether desktoppr manage will re-set the wallpaper every time it runs (when setOnlyOnce is false) or only when the picture key in the profile changed (when setOnlyOnce is true). Configuring setOnlyOnce to true allows a user to change the wallpaper and it will not be overridden until you change the configuration profile. Then the user can change it again. This seemed like a useful compromise between management and user choice to me.
The scale and color keys work just like the options of the command line tool. Note that setting the color option is broken in macOS 14 as of this writing.
You can of course use different combinations of LaunchAgent configuration and other triggers for desktoppr, such as a self service portal to get all kinds of different workflows and levels of ‘lockdown.’ Remember that Apple provides a config profile setting to fully set and lock the wallpaper.
I have found this new managed desktoppr option useful in my deployments. I hope you do, too. Let me know!
Recently I have been working on some… well… “stuff” that uses custom configuration profiles. Very custom, and since I am testing things, they need to be updated a lot.
defaultsWhen you are working with defaults/preferences/settings/property lists on macOS, you will be familiar with the defaults command line tool. But, as useful as defaults can be, it has some downsides.
One of the great advantages of macOS’ preference system is that settings can be provided on multiple levels or domains. In my book “Property Lists, Preferences and Profiles for Apple Administrators, I have identified 19 different levels where settings for a single application can originate.
You will be most familiar with plist files in /Library/Preferences (system), ~/Library/Preferences (user), and managed configuration profiles (managed). When an app or tool requests a setting, the preferences system will merge all those levels together and present only the most relevant value. When the developer uses the system APIs (correctly), they do not have to worry about all the underlying levels, domains and mechanisms very much, but automatically gain support for things like separated system and user level settings files and support for management through configuration profiles.
The macOS defaults command line tool can work with settings on different levels or domains, but will only show the settings from one at a time. By default it only works with the user domain settings stored in ~/Library/Preferences/. When you have settings in multiple levels or from configuration profiles, you may be able to point defaults directly at the files. Or in the case of managed settings from profiles, you have to use a different tool. Either way, you have to determine which setting might override another and which final value might be visible to the app or process.
prefs toolYears back, I had built a python script, called prefs.py, which would not only show the coalesced set of settings but their origin level. When macOS removed Python 2 in macOS 12.3, this tool obviously broke.
While working with preferences and profiles recently, this feature would have been quite useful to debug and verify preferences. I could have adapted the existing tool to work with MacAdmins Python 3, but felt I would learn something from recreating it in Swift. I had already started down that road just a bit for my sample project in this post.
So, you can find the new Swift-based prefs command line tool on GitHub. You can also download a signed and notarized pkg which will install the binary in /usr/local/bin/.
If its most basic form, you run it with a domain or application identifier. It will then list the merged settings for that preference domain, showing the level where the final value came from.
% prefs com.apple.screensaver
moduleDict [host]: {
moduleName = "Computer Name";
path = "/System/Library/Frameworks/ScreenSaver.framework/PlugIns/Computer Name.appex";
type = 0;
}
PrefsVersion [host]: 100
idleTime [host]: 0
lastDelayTime [host]: 1200
tokenRemovalAction [host]: 0
showClock [host]: 0
CleanExit [host]: 1I find this useful when researching where services and applications store their settings and also to see if a custom configuration profile is set up and applying correctly. There is a bit of documentation in the repo’s ReadMe and you can get a description of the options with prefs --help.
plist2profileAnother tool that would have been useful to my work, but that was also written in python 2 is Tim Sutton’s mcxToProfile. Back in the day, this tool was very useful when transitioning from Workgroup Manager and mcx based management to the new MDM and configuration profile based methods. If you have a long-lived management service, you will probably find some references to mcxToProfile in the custom profiles.
Even after Workgroup Manager and mcx based settings management was retired, Tim’s tool allowed to create a custom configuration profile from a simple property list file. Configuration Profiles require a lot of metadata around the actual settings keys and values, and mcxToProfile was useful in automating that step.
Some management systems, like Jamf Pro, have this feature built in. Many other management systems, however, do not. (Looking at you Jamf School.) But even then creating a custom profile on your admin Mac or as part of an automation, can be useful.
So, you probably guessed it, I also recreated mcxToProfile in Swift. The new tool is called plist2profile and available in the same repo and pkg. I have focused on the features I need right now, so plist2profile is missing several options compared to mcxToProfile. Let me know if this is useful and I might put some more work into it.
That said, I added a new feature. There are two different formats or layouts that configuration profiles can use to provide custom setting. The ‘traditional’ layout goes back all the way to the mcx data format in Workgroup Manager. This is what mcxToProfile would create as well. There is another, flatter format which has less metadata around it. Bob Gendler has a great post about the differences.
From what I can tell, the end effect is the same between the two approaches. plist2profile uses the ‘flatter’, simpler layout by default, but you can make it create the traditional mcx format by adding the --mcx option.
Using it is simple. You just need to give it an identifier and one or more plist files from which it will build a custom configuration profile:
% plist2profile --identifier example.settings com.example.settings.plistYou can find more instructions in the ReadMe and in the commands help with plist2profile --help
As I had anticipated, I learned a lot putting these tools together. Not just about the preferences system, but some new (and old) Swift strategies that will be useful for the actual problems I am trying to solve.
I also learnt more about the ArgumentParser package to parse command line arguments. This is such a useful and powerful package, but their documentation fails in the common way. It describes what you can do, but not why or how. There might be posts about that coming up.
Most of all, these two tools turned out to be useful to my work right now. Hope they will be useful to you!
A long time ago, I wrote a post on how to build a simple App using SwiftUI that would run a shell command. Amazingly, the tutorial still works!
This is particularly useful for MacAdmins, because we sometimes want to provide a simple UI for some command or script. However, some things have changed since I wrote this tutorial three years. While the code still “works,” there are some things that can be improved. Also, when I wrote the original post, there were some features I didn’t expand upon, because the post was already very long, and, to be honest, back then, I didn’t really know how they worked, myself.
When I re-visited this earlier because of a question in the MacAdmins Slack, I was really surprised that I didn’t need to update code to make it work. That said, there are the matters I didn’t explain last time. Also Swift has changed in some ways. That means it is time for the second part.
You can get the sample code from the first part as a starting point.
In the first part, we ran the say command, which doesn’t have a text output. Often times we want to run shell commands to get information from the command’s standard output (or sometimes standard error). To grab the output of commands, we need to prepare the Process object, which means we cannot use the convenience method Process.run() any more.
The say command has an option to change the voice being used. You can list the names of voices available to the say command by running say -v '?' in Terminal. We’d like to get that output and populate a menu with the available voices in our UI.
Note: the output of the say -v '?' command does not show most of the modern voices available in macOS. Most of the voices listed are quite old, funny, and, to be honest, awful. As has been mentioned before, I am using the say command as a convenient example for a shell command. If you want proper speech synthesis in your app, you should not use the say command but the proper speech synthesis API.
We will start out experimenting with code in a macOS Playground in Xcode and later add it to the app from the first part. When you create a new Playground in Xcode (File > New > New Playground), make sure you select ‘macOS’ for the platform above the template picker and then ‘Blank’ as the template.
Start with this code:
let process = Process()
process.launchPath = "/usr/bin/say"
process.arguments = ["-v", "?"]
let outPipe = Pipe()
process.standardOutput = outPipe
process.terminationHandler = { process in
let outData = outPipe.fileHandleForReading.readDataToEndOfFile()
let output = String(data: outData, encoding: .utf8) ?? ""
print(output)
}
try? process.run()
process.waitUntilExit()You will recognize some of the code from the first part of this tutorial. We create a Process object and set its launchPath and arguments. Note that the Process.run() convenience method, which we used in the first part, takes a URL to define the executable, but the launchPath is a String containing the path to the executable. We also (this is the new part) create a Pipe and set it as the standardOutput of the process.
The process will run the say command asynchronously. Since we want to work with the output , we have to give the process some code to execute when the command is done. We set this terminationHandler to a closure. The code in this closure grabs the data from pipe we connected to standardOutput of the process, converts it to a String and prints it.
At the end of our code, we tell the process object to run(). The waitUntilExit() is necessary here, because that is all this particular playground code does and we want to be sure that the command and the termination handler get a chance to do their work, before the code ends. In an app, where many things may be happening at the same time, you usually will not use waitUntilExit(). We will see that later when we implement our solution in SwiftUI.
This code grabs the standard out from the command. Unix commands have different results that can be interesting. Some commands print to standard error instead of (or together with) standard out. All unix commands also have an exit code, which should return 0 for successful runs and a non-zero value for failures. Some commands use different non-zero value to give information for different errors.
All of this is available from Process objects. However, you have to set up the pipes and connections and get the data back in the termination handler, and the code gets quite complicated and tedious to set up. We have the seen the Process type has a convenience method to create and run a command without the pipes. I don’t know why it doesn’t have a convenience method when you are interested in all the data, but the good news is, we can create an extension to build our own.
Replace the code in the playground with the following:
import Foundation
extension Process {
@discardableResult
static func launch(
path: String,
arguments: [String] = [],
terminationHandler: @escaping (Int, Data, Data) -> Void
) throws -> Process {
let process = Process()
let outPipe = Pipe()
let errorPipe = Pipe()
process.standardOutput = outPipe
process.standardError = errorPipe
process.arguments = arguments
process.launchPath = path
process.terminationHandler = { process in
let outData = outPipe.fileHandleForReading.readDataToEndOfFile()
let errorData = errorPipe.fileHandleForReading.readDataToEndOfFile()
let exitCode = Int(process.terminationStatus)
terminationHandler(exitCode, outData, errorData)
}
try process.run()
return process
}
}
let process = try? Process.launch(
path: "/usr/bin/say",
arguments: ["-v", "?"]
) { exitCode, outData, errData in
let output = String(data: outData, encoding: .utf8) ?? ""
print(output)
}
process?.waitUntilExit()You will recognize the code from our first example in the launch function in the extension. But here, we have added the configuration for a second Pipe for standardError, in the closure we get the Data for the standard out, standard error and the exit code and pass them in to the closure passed in a termination handler.
This method simplifies using the Process type. We just have to pass in the path to the command and the arguments array and give a closure that is called when the command completes.
But it still uses a closure for the termination handler. This breaks our code into different fragments that are not executed in the order they appear in. Since macOS Monterey 12 and iOS 15, Swift has had a concurrency feature called async/await. With this, your code appears in a more natural order.
When a function has the await marker, the system knows to suspend the code at that point until the function returns a result. While this code is “on hold” other threads or tasks can run, such as the UI handling, so your process or app isn’t blocked. When the function returns, the code continues after the function, so the code that processes the output of the function comes in the logical order, which makes it easier to read and understand.
For some reason, the Process type has not yet been updated to use this new feature. We can however, add this functionality using an extension. Add this method to the extension:
static func launch(
path: String,
arguments: [String] = []
) async throws -> (exitCode: Int, standardOutput: Data, standardError: Data) {
try await withCheckedThrowingContinuation { continuation in
do {
try launch(path: path, arguments: arguments) { exitCode, outData, errData in
continuation.resume(returning: (exitCode, outData, errData))
}
} catch let error {
continuation.resume(throwing: error)
}
}
}If you want to get more detail how async and await work, I recommend the WWDC session “Meet async/await in Swift” from WWDC 2021.
With this, we can change our code to run the say command to:
guard let (exitCode, outData, errData) = try? await Process.launch(
path: "/usr/bin/say",
arguments: ["-v", "?"]
) else { exit(0) }
let output = String(data: outData, encoding: .utf8) ?? ""
print(output)The code is now in a more sensible order. If you can afford macOS Monterey as a minimum system requirement, you should consider adopting async/await.
Now that we have our output of the command, we have to parse out the names of the voices. This code will turn the output of the say into an Array of names, ignoring the language code and sample text:
func parseVoices(_ output: String) -> [String] {
output
.components(separatedBy: "\n")
.map {
$0
.components(separatedBy: "#")
.first?
.trimmingCharacters(in: .whitespaces)
.components(separatedBy: CharacterSet.whitespaces)
.dropLast()
.filter { !$0.isEmpty }
.joined(separator: " ")
?? ""
}
.filter { !$0.isEmpty }
}So we can add these lines to get an Array of `voices:
let voices = parseVoices(output)
print(voices)You can find the stages of code for the playground in this gist.
Now that we have assembled all the pieces working in a playground, we can move on to putting these pieces in our SwiftUI app. The goal is to have a popup menu with all the voices above the field where you can enter text.
We will be using some features that were introduced in macOS Monterey 12.0. If you have built the project a while ago with an older version of macOS, the project may be set to build with older versions of macOS. To verify and, if necessary, update the deployment target for the project, select the blue project icon at the very top of the item sidebar, then select the gray “SayThis” icon under the “Targets” section. Then select “General” in the tab list. The second section is called “Minimum Deployments” and should show macOS 12.0 or later. When you change this from an older version, Xcode may prompt to update some other settings in the project, you can accept those.
First, we want to use the extension to the Process type we created in the playground earlier. Create a new file in the project (File > New > New File…), select “Swift File” from the templates, and name it ‘Process-launch’. Copy and paste the extension code from the playground (with both methods) to that file. You could have all the code in a single file, but it is cleaner and more maintainable to have one file per type or extension. This also allows you to copy that file to other projects to use it there.
Next we need two more state variables to track the state of the popup-menu that we are going to add. In the ContentView file, add these two lines right under the existing @State variables:
@State var voices: [String] = []
@State var selectedVoice: String = "Samantha"The first is where we are going to store all the available voices that we parse from the output of say -v '?'. The second variable will store the current selection.
Next, we will insert the popup menu for the voices into the UI. In the body, insert this below the title and above the HStack:
Picker(selection: $selectedVoice, label: Text("Voice:")) {
ForEach(voices, id: \.self) { Text($0) }
}First we create a Picker view, which is not really proper terminology for macOS. But since SwiftUI is designed to share objects across all platforms, a ‘Picker’ will render as a popup menu in macOS. We attach the selectedVoice state variable to the selection of the picker. Then, we loop through all the items in the voices state variable to add them to the picker.
At this point, you should see the popup menu in the preview and when you run the project. You cannot select anything from it, though, which makes sense as the voices array is empty.
We need to populate the voices array before the UI appears. SwiftUI offers a special modifier to do this. You can attach a .task modifier to any view and its closure will be run asynchronously once, before the view appears for the first time. Add this code to the end of the VStack block, right below the line that reads .frame(maxWidth: .infinity, maxHeight: .infinity):
.task {
guard let (_, outData, _) = try? await Process.launch(
path: "/usr/bin/say",
arguments: ["-v", "?"]
) else { return }
let output = String(data: outData, encoding: .utf8) ?? ""
voices = parseVoices(output)
}You also need to copy the parseVoices() function from the test playground and add it to the ContentView struct.
This will populate the popup menu with all the voices. Build and run to test. It will still not actual use the selected voice. We need to update the runCommand() method to:
func runCommand() {
let arguments = [message, "-v", selectedVoice]
let executableURL = URL(fileURLWithPath: "/usr/bin/say")
self.isRunning = true
try! Process.run(executableURL, arguments: arguments) { _ in
self.isRunning = false
}
}We have achieved what we set out to do. You can find the project with all the code for this point here.
However, there are some refinements and improvements that we can and should still add to the code.
First, the runCommand() function still uses the old convenience handler with a termination handler. We can change it to use our new await Process.launch():
func runCommand() async {
let arguments = [message, "-v", selectedVoice]
self.isRunning = true
let _ = try? await Process.launch(path: "/usr/bin/say", arguments: arguments)
self.isRunning = false
}This will now generate an error in the Button because we have changed the runCommand() function to be async. Change the code of the Button to
Button("Say") {
Task {
await runCommand()
}
}
.disabled(isRunning)By wrapping the await runCommand() function in a Task { } we are telling the system that this code should run in the background and not return immediately. This is necessary to run code blocks with async functions from UI elements.
The say command will use the voice set in the system settings when no -v option is given. We want to provide a way to recreate that behavior in our UI. We can add items to the Picker by adding elements before the ForEach:
Picker(selection: $selectedVoice, label: Text("Voice:")) {
Text("System Default").tag("System Default")
Divider()
ForEach(voices, id: \.self) { Text($0) }
}Also change the default value of the selectedVoice variable to "System Default".
Then we have to change the runCommand() method to only use the -v and voice name arguments when their value is not “System Default”
func runCommand() async {
var arguments = [message]
if selectedVoice != "System Default" {
arguments.append(contentsOf: ["-v", selectedVoice])
}
self.isRunning = true
let _ = try? await Process.launch(path: "/usr/bin/say", arguments: arguments)
self.isRunning = false
}You can find the code for this here.
The say command provides a fun example to play around with. You will probably already have plenty of ideas that you want to try out. There is one thing that might trip you up here: sandboxed apps do not get access to all available command line tools. If you want to run such ‘prohibited’ commands, you will need to remove the sandbox configuration from the app.
The extension I put together here will work in most situations, but there are conditions where different parts might not work well. Quinn the Eskimo has published this code which goes further and is probably “even more” thread safe.
Launching commands is an “expensive” task. You should always do some research to see if there is some framework that can give you access to the same functionality natively in Swift. Nevertheless, sometimes it might be necessary, and sometimes it might just be easier to call out to an external command.
This tutorial should help you along the way of using these tools effectively.
RAIDs are a strange edge case that are rarely useful outside of servers, but when they are useful, they are very important. RAID is an acronym for ‘Redundant Array of Independent/Inexpensive Disks.’ It is a technology where you combine multiple, physical disks into a single virtual drive for redundancy, speed, or both.
Often the RAID system is handled by a dedicated controller in an external enclosure, but sometimes, you want or need to work with drives directly. macOS has some basic RAID functionality built-in and there are good third party options if you want to go further.
If you are unfamiliar with RAIDs, we need to get some terminology sorted out first. There are different kinds of RAIDs which are called ‘levels.’
In this post, I am going to focus on level 1 or ‘RAID 1.’ With RAID 1, the data is ‘mirrored’ between two or more drives, so that each drive carries a complete copy of the data. This protects from data loss because of drive failure. Note that RAID 1 does not protect from other common reasons for data loss, such as file system or individual file corruption, accidental or malicious file deletion. A RAID is never a replacement for a good backup strategy. Since the data is mirrored on all the devices, a RAID 0 will only have the capacity of the smallest drive in the set. It is generally recommended that drives in any RAID set should be of the same capacity and type, for best performance and efficiency.
A level 0 RAID (or ‘RAID 0’) is not actually redundant. In a RAID 0 the data is ‘striped’ across two or more drives so that writes and reads happen in parallel, which increases the data bandwidth available. Since the data is spread evenly (striped) across all drives in the RAID 0 set, failure of a single drive will result in complete data loss. The capacity of the stripe raid is the capacity of the smallest drive in the set multiplied by the number of drives in the set. Having drives of the same type and capacity is even more relevant for RAID 0 performance.
There are more RAID levels, such as 0+1, 10 and 5 and dedicated disk controllers will have more options (such as combining multiple drives of different sizes more efficiently), but we will focus RAID 1 (mirror).
Warning: many of the commands shown here to setup and experiment with disk drives and RAIDs may or will lead to loss of the data on the drives involved, so be careful. I strongly recommend disconnecting any drives other than those you are experimenting with from the Mac you are working on.
I would also recommend to experiment with a set of drives that contain no relevant data at all. Two USB sticks will do just fine to explore and test the functionality. Drives do not have to be of the same capacity and type for testing, but I do recommend that for actual use.
macOS has built-in support for software-based mirror and stripe RAID called “AppleRAID.” This also provides a third option to concatenate drives, but concatenation provides neither redundancy, nor performance, so I do not recommend using it.
You can use the Disk Utility app to setup a RAID. It has a nice assistant that you an access from the File menu called RAID Assistant. It will ask you what kind of RAID you want to setup and allow you to select the drives and create a new RAID volume. This will delete the data on the disk drives and there are few features that are not exposed in the Disk Utility UI, so I will focus on how to do it in the command line.
You can keep Disk Utility open to get a visual representation of what is going on, though the Disk Utility app often has problems keeping up with changes done from the command line. You may have to quit and restart the app to force it to update its status. You want to enable “Show all Devices” from the View menu to see the physical drives as well as the file systems and virtual drives.
First, we need to identify the disks that we want to work with. When you run diskutil list it will list all the disk on the system. Usually disk0 will be the built-in drive, and disk3 will be the (synthesized) APFS container inside (with the System and Data volume). But depending on what Mac you are using, what your configuration is, and what devices you had attached to the Mac before you started this, the numbers may be different.
Again, to be safe, unmount and disconnect any drives or file servers with data that you care about at this point, and the connect the two drives you want to use for experimentation. Their data will be erased!
Run diskutil list again and identify the device identifiers for the drives you will be working with. They should look like this:
/dev/disk4 (external, physical):For me, the two drives where disk4 and disk5, so I will be using those numbers in my examples, but be sure to replace those with the device numbers on your system, other wise you might be working with the wrong disk or volume.
One of the features you can use from the command line is to ‘promote’ an existing drive to a mirror RAID without data loss. Apple RAID promotion works (as far as I can tell) only with HFS+ formatted Volumes, so let us reformat the first disk (disk4) as such:
> diskutil eraseDisk JHFS+ DiskName disk4
Started erase on disk4
Unmounting disk
Creating the partition map
Waiting for partitions to activate
Formatting disk4s2 as Mac OS Extended (Journaled) with name DiskName
Initialized /dev/rdisk4s2 as a 59 GB case-insensitive HFS Plus volume with a 8192k journal
Mounting disk
Finished erase on disk4Using the command line, we will be able to promote this HFS+ drive without have to erase it (again), so copy some (un-important) files to it now.
diskutil has a sub-group of commands dedicated to the RAID functions called appleRAID or ar for short. I am going to use the short form. You can run diskutil ar to get a list of the sub-commands for working with Apple Raid. You can read the diskutil man page for details.
Next we have to enable AppleRAID on the drive. Enabling RAID on single drive seems a bit pointless, but this prepares everything on that drive, so that we can add more drives later.
> diskutil ar enable mirror DiskName
Started RAID operation on disk4s2 (DiskName)
Resizing disk
Unmounting disk
Adding a booter for the disk
Creating a RAID set
Bringing the RAID partition online
Waiting for the new RAID to spin up "8D05B6EB-DCFB-426D-885B-ED8C76DC2484"
Finished RAID operation on disk4s2 (DiskName)The volume and the files you had copied earlier are still there. But the volume is now listed under “RAID Sets” in Disk Utility. You can see the single drive in the RAID Set in the UI there. You can also get this info in command line with
> diskutil ar list
AppleRAID sets (1 found)
===============================================================================
Name: DiskName
Unique ID: 8D05B6EB-DCFB-426D-885B-ED8C76DC2484
Type: Mirror
Status: Online
Size: 63.8 GB (63816400896 Bytes)
Rebuild: manual
Device Node: disk6
-------------------------------------------------------------------------------
# DevNode UUID Status Size
-------------------------------------------------------------------------------
0 disk4s2 467826B1-BBA2-4671-99CE-5CBB04E06882 Online 63816400896
===============================================================================To make this a real mirror RAID, we need to add the second drive:
> diskutil ar add member disk5 DiskName
Started RAID operation on disk6 (DiskName)
Unmounting disk
Repartitioning disk5 so it can be in a RAID set
Unmounting disk
Creating the partition map
Adding disk5s2 to the RAID Set
Finished RAID operation on disk6 (DiskName)This will add the drive to the RAID. This will delete any data that might be on disk5!
When you look at the RAID in Disk Utility (you might have to restart the app for it to pick up the new status) you will now see both drives, but one of them has the status “Rebuilding” with a percentage. The status of the entire RAID set is now “Degraded.” The RAID system is still in the process of mirroring data to the new member. You can use the volume to read and write data at this time, but it is not redundant yet. If the first drive fails during rebuilding, the data will be gone.
Once the rebuilding is done, the status of the RAID will change to “Online,” which is the “good” status. At this point the data on the RAID will be resilient to the failure or removal of either of the drives.
You can also create the RAID with both drives from the start, but this will erase all the data on both drives (this is what RAID Assistant in Disk Utility does.
Before we can try the other way of creating a mirror RAID set, we need to “break” the mirror we have built so far.
> diskutil ar delete DiskName
Started RAID operation on disk6 (DiskName)
Unmounting volume for RAID set 8D05B6EB-DCFB-426D-885B-ED8C76DC2484
Destroying the RAID set 8D05B6EB-DCFB-426D-885B-ED8C76DC2484
Finished RAID operation on disk6 (DiskName)If you waited for the rebuilding to be complete, both individual drives will each contain the data of the former mirror RAID. If the rebuilding was not complete yet, only the first drive will contain the data, the second drive will be empty.
Now let’s build a new empty mirror RAID with both drives included from the start:
> diskutil ar create mirror DiskName APFS disk4 disk5
Started RAID operation
Unmounting proposed new member disk4
Unmounting proposed new member disk5
Repartitioning disk4 so it can be in a RAID set
Unmounting disk
Creating the partition map
Using disk4s2 as a data slice
Repartitioning disk5 so it can be in a RAID set
Unmounting disk
Creating the partition map
Using disk5s2 as a data slice
Creating a RAID set
Bringing the RAID partitions online
Waiting for the new RAID to spin up "FE3E7A3F-E4BF-4AEE-BC3C-094A9BFB3251"
Mounting disk
Finished RAID operationNote that we can build an APFS volume on the RAID set with the command line tool. RAID Assistant in Disk Utility will build a HFS+ volume. In this new empty RAID set both drives will be online immediately.
When you replace the mirror with stripe in this command you will get a striped RAID 0 volume. (performance instead of redundancy)
We can simulate a drive failure by unplugging one of the members. Sadly, macOS does not seem to have a notification for this event. Once you have removed the drive you can run disktutil ar list and see the status is “Degraded” and the which member is “Missing/Damaged.” You can keep using the volume in degraded mode.
Once you plug the drive back in it will appear as ‘failed.’ You can start the process of repairing or rebuilding the mirror with
> diskutil ar repairMirror FE3E7A3F-E4BF-4AEE-BC3C-094A9BFB3251 disk5
Started RAID operation
Unmounting disk
Repartitioning disk5 so it can be in a RAID set
Unmounting disk
Creating the partition map
Adding disk5s2 to the RAID Set
Finished RAID operation
Note: Syncing data between mirror partitions can take a very long time.
Note: The mirror should now be repairing itself. You can check its status using 'diskutil appleRAID list'.The UUID is the UniqueID of the RAID set you see with diskutil ar list. The warning you get at the end is fair. The rebuilding process will take a while. How it takes depends on how full the volume is and how fast the new member drive is.
There are quite a few downsides to the built-in AppleRAID functionality. There is no notification or warning when one of the drives in a mirror goes offline and the RAID is running in degraded state. The RAID will also not automatically rebuild when a missing drive re-appears. (There is an AutoRebuild option mention in man page, but whenever I tried to enable that, the entire disk management stack froze in a way that required a reboot.)
AppleRAID can be useful to quickly stripe some random disks for performance. But generally, if the data was of so much concern that I am considering RAID 1, I would not rely on AppleRAID.
There is a wonderful third party tool for managing software based RAIDs on macOS called SoftRAID (14-day free trial, then a tiered license). And, much to my delight, it also comes with a command line tool. Creating a RAID is not something you do regularly, so I went ahead and did this in the GUI app. Once that was setup, I used the command line tool to get the RAID’s status:
> softraidtool volume DiskName info
Info for "DiskName":
Mountpoint: /Volumes/DiskName
BSD disk: disk4
Total Bytes: 59.6 GB (64,016,478,208)
Free Bytes: 59.6 GB (64,016,478,208)
Volume format: unknown
Volume is DiskName
RAID level: RAID 1
DiskName ID: 09DF05C72BFFAD20
Optimized for: Workstation
Created: Jul 17, 2023 at 3:33:39 PM
Last Validated: never
Volume state: normal,
Volume Safeguard: enabled
Total I/Os: 5,610
Total I/O Errors: 0
Total number secondary disks (including offline ones): 1
Disks used for this volume:
bsd disk: SoftRAID ID: Location and Size:
disk7 09DF053ECE82F980 (USB3 bus 0, id 4 - 59.8 GB) secondary disk,
disk6 09DF053D23386500 (USB3 bus 0, id 5 - 59.8 GB) primary disk, The SoftRAID software also comes with a menubar app that shows the status of the RAID.
When you unplug one of the drives, the ‘Volume state’ changes to ‘missing disk.’ When you plug the missing drive back in, SoftRAID will automatically detect it and rebuild the RAID, when necessary. Rebuilding went so quickly that I had a hard time capturing the state from the command line. The more changes you apply to the degraded RAID the longer the rebuild takes.
> softraidtool volume SoftRAID info
SoftRAIDTool status: waiting for disk5 to finish (00:00:01)
Info for "SoftRAID":
Mountpoint: /Volumes/SoftRAID
BSD disk: disk5
Total Bytes: 59.6 GB (64,016,478,208)
Free Bytes: 59.6 GB (64,016,478,208)
Volume format: unknown
Volume is SoftRAID
RAID level: RAID 1
SoftRAID ID: 09DF06D95024CBE0
Optimized for: Workstation
Created: Jul 17, 2023 at 3:53:16 PM
Last Validated: never
Volume state: rebuiding, out of sync,
Volume Safeguard: enabled
Volume progress: 15%
Current offset: 7,343,685,632
Time remaining: 00:07:24
Total I/Os: 22,752
Total I/O Errors: 0
Total number secondary disks (including offline ones): 1
Disks used for this volume:
bsd disk: SoftRAID ID: Location and Size:
disk4 09DF053ECE82F980 (USB3 bus 0, id 4 - 59.8 GB) primary disk,
disk7 09DF053D23386500 (USB3 bus 0, id 5 - 59.8 GB) secondary disk, rebuiding, out of sync, You can parse this output using awk to get just the volume state. This is useful for reporting the state to Jamf Pro with an extension attribute:
#!/bin/sh
# reports the SoftRAID status
softraidtool="/usr/local/bin/softraidtool"
if [ ! -x "$softraidtool" ]; then
echo "<result>SoftRAID not installed</result>"
fi
volumestate=$(softraidtool volume SoftRAID info | awk -F ': ' '/Volume state/ {print $2}')
echo "<result>$volumestate</result>"Keep in mind that Jamf Inventory Updates (aka as recon) may run very infrequently (recommended default is once per day, and it shouldn’t run much more often than that to avoid database bloat), so the data in your Jamf Pro may be hours or sometimes longer out of date. If you want to react to changes in the RAID status more quickly, you should rely on other tools than Jamf Pro.
The best solution for RAIDs will always be a dedicated hardware controller. But there also good reasons (cost) to just put together a “bunch of disks” into a RAID. The built-in AppleRAID functionality works, but has limitations, especially for mirror RAIDs. SoftRAID is a great tool to overcome these limitations. For Mac admins, both can be managed and monitored with command line tools, which allows automation and integration with your management system.
I have written about man pages before. That post references an even older post, which is actually the second oldest post on this blog. Most of the recommendations in the posts still hold true, but there is one change relevant to macOS Ventura and one other thing that is worth adding.
Ventura’s Preview app lost the ability to render postscript or ps files. This breaks the previous, popular shell alias to open a man page in Preview. However, the amazing community in the #scripting channel of the MacAdmins Slack have figured out a replacement. They have asked me to share it.
Add this function to your shell configuration file: (bash, zsh)
preman() {
mandoc -T pdf "$(/usr/bin/man -w $@)" | open -fa Preview
}
Then you can run preman <command> in Terminal and the man page will render beautifully in Preview. If you want to override the man command to actually use this function instead of the built-in command, add this alias:
alias man preman
If you then need to revert to the actual man command for a test of something, just add \ before the command: \man <command>
Update: Pico has expanded this into a full blown script which caches the pdfs.
Myself, I had not noticed this change, because I prefer opening the ‘yellow’ man pages in Terminal app. You can do so by entering a command in the Help menu, or by using the x-man-page URL scheme. In these yellow terminal windows, you can scroll and search in the text with command-F. You can also do a secondary click (right/ctrl/two-finger click) on any word and it will offer to open that man page in the context menu.
If the yellow man page windows annoy you, you can change their appearance by modifying Terminal’s “Man Page” profile. I modify it to use my favorite mono spaced font at a larger size. I like the yellow background because it stands out.
In the previous posts, I had a simple function you could add to your shell configuration files, but I have since refined this to also support man page sections (the number you sometimes see after a command, you can learn what they mean in the man page for the man command).
xmanpage() {
if [[ -z $2 ]]; then
open x-man-page://"$1"
else
open x-man-page://"$1"/"$2"
fi
}
With this, you can open the desired section in the ‘yellow’ man window with xman 2 stat. This works already with the preman function. The mandoc command knows how to deal with the extra argument, the URL scheme needs a bit of extra work.
If you want to override the normal man command you can, again, use an alias in your shell configuration file:
alias man xmanpage
This way, I can have both functions in the configuration file and choose or change which function (if any) overrides the normal man by just changing the alias.
When you work in Terminal for a while you may accumulate a lot of yellow man page windows. You can use this AppleScript/osascript one-liner to close all Terminal windows which use the ‘Man Page’ profile at once.
osascript -e 'tell application "Terminal" to close (every window where name of current settings of every tab contains "Man Page")'
And while this one-liner is succint, it is still easier to wrap this in a function for your shell configuration file:
closeman() {
osascript -e 'tell application "Terminal" to close (every window where name of current settings of every tab contains "Man Page")'
}
If you enjoyed this excursion into macOS Terminal and command line tricks and configuration, you might like one of my books: “macOS Terminal and shell” and “Moving to zsh”.
In the last post, we discussed how to run shell commands and scripts from an Apple Script environment. In this post, we will look at how we can run AppleScript commands and scripts from the shell environment.
The key to running AppleScript from the shell is the osascript command. OSA is short for ‘Open Scripting Architecture’ which is the framework that powers AppleScript. This framework allows AppleScript to have its native language, but also use JavaScript syntax.
The osascript command allows us to run AppleScript commands from Terminal and shell. The most common use is the user interaction commands from AppleScript, like display dialog:
osascript -e 'display dialog "Hello from shell"'The -e option tells osascript that it will get one or more lines of statements as arguments. The following argument is AppleScript code. You can have multiple -e options which will work like multiple lines of a single AppleScript:
> osascript -e 'display dialog "Hello from shell"' -e 'button returned of result'
OKosascript prints the value of the last command to stdout. In this case, it is the label of the button clicked in the dialog. (The ‘Cancel’ button actually causes the AppleScript to abort with an error, so no label will be returned for that.)
When you have multiple lines of script, using multiple -e statements will quickly become cumbersome and unreadable. It is easier to use a heredoc instead:
osascript <<EndOfScript
display dialog "Hello from shell"
return button returned of result
EndOfScriptThis also avoids the problem of nested quotation marks and simplifies shell variable substitution.
There are a few ways to pass data into osascript from the shell.
Since the shell substitutes variables with their value before the command itself is actually executed, this works in a very straightforward manner:
computerName=$(scutil --get ComputerName)
newName=$(osascript -e "text returned of (display dialog \"Enter Computer Name\" default answer \"$computerName\")")
echo "New Name: $newName"This works well, but because we want to use shell variable substitution for the $computerName, we have to use double quotes for the statement. That means we have to escape the internal AppleScript double quotes and everything starts to look really messy. Using a heredoc, cleans the syntax up:
computerName=$(scutil --get ComputerName)
newName=$(osascript <<EndOfScript
display dialog "Enter Computer Name" default answer "$computerName"
return text returned of result
EndOfScript
)
echo "New name: $newName"I have a detailed post: Advanced Quoting in Shell Scripts.
Generally, variable substitution works well, but there are some special characters where it might choke. A user can put double quotes in the computer name. In that case, the above code will choke on the substituted string, since AppleScript believes the double quotes in the name end the string.
If you have to expect to deal with text like this, you can pass data into osascript using environment variables, and using the AppleScript system attribute to retrieve it:
computerName=$(scutil --get ComputerName)
newName=$(COMPUTERNAME="$computerName" osascript <<EndOfScript
set computerName to system attribute "COMPUTERNAME"
display dialog "Enter Computer Name" default answer computerName
return text returned of result
EndOfScript
)
echo "New name: $newName"The shell syntax
VAR="value" command arg1 arg2...sets the environment variable VAR for the process command and that command only. It is very useful.
Retrieving environment variables in AppleScript using system attribute is generally a good tool to know.
osascript can also work as a shebang. That means you can write entire scripts in AppleScript and receive arguments from the shell. For example, this script prints the path to the front most Finder window:
#!/usr/bin/osascript
tell application "Finder"
if (count of windows) is 0 then
set dir to (desktop as alias)
else
set dir to ((target of Finder window 1) as alias)
end if
return POSIX path of dir
end tellYou can save this as a text file and set the executable bit. I usually use the .applescript extension.
> print_finder_path.applescript
/Users/armin/DocumentsTo access arguments passed into a script this way, you need to wrap the main code into a run handler:
#!/usr/bin/osascript
on run arguments
if (count of arguments) is 0 then
error 2
end if
return "Hello, " & (item 1 of arguments)
endYou can combine this into a longer script:
When you ran the above script, you may have gotten this dialog:
If you didn’t get this dialog, you must have gotten it at an earlier time and already approved the access.
AppleEvents between applications are controlled by the macOS Privacy architecture. Without this, any process could use AppleEvents to gather all kinds of data from any process. These dialogs are easy enough to deal with when running from Terminal. But if you put your AppleScript code (or shell scripts calling AppleScript) into other apps or solutions, it could get messy quite quickly.
Mac Admins generally want their automations to run without any user interactions. You can avoid these dialogs by creating PPPC (Privacy Preferences Policy Control) profiles that are distributed from an MDM server. In this case you have to pre-approve the application that launches the script, which can sometimes also be challenge. The other option is to find solutions that avoid sending AppleEvents altogether.
I have a longer post detailing this: Avoiding AppleScript Security and Privacy Requests
Management scripts often run as a privileged user or root. In this case, certain features of AppleScript may behave strangely, or not at all. I generally recommend to run osascript in the user context, as detailed in this post: Running a Command as another User
AppleScript’s bad reputation may be deserved, because its syntax is strange, and often very inconsistent. Nevertheless, it has features which are hard to match with other scripting languages. You can use the strategies from this and the previous posts to combine AppleScript with Shell Scripting and other languages to get the best of both worlds.