Rename Computer - Rocketman-Tech/rcc GitHub Wiki

The Rename Computer tool programmatically renames macOS computers based on a customizable naming scheme. This tool retrieves system and configuration data, applies user-defined formatting, and sets the new computer name using Jamf.

Quick Start

This quick start guide will show you how to programmatically rename the computer with the first 6 characters of the Serial Number, followed by a dash, followed by the first 8 characters of their Local Username, all in uppercase.

For example, a computer might be renamed to MX59HX-CHRISSCH.

To do this, we will need to create the following:

Configuration Profile
Policy

Example Configuration Profile

Below is a Managed PLIST that can be deployed through a Configuration Profile to the following domain: tech.rocketman.rename

<?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>computerName</key>
    <string>%=SERIAL:6%-%=LOCALUSERNAME:8%</string>
    <key>case</key>
    <string>upper</string>
  </dict>
</plist>

Example Policy

hen setting up the Launch a Tool Script in Jamf Pro, use the following script parameters:

Parameter 4 (Global Options and Tool Name):
```
RenameComputer
```

Command Options

Required Parameters

`--computerName`

Specifies the naming scheme for the computer. The scheme supports tokens enclosed in % that are replaced with values derived from local and managed sources. Important: All tokens that are intended for dynamic substitution must include an equals sign (=) immediately after the opening %. Tokens written without the equals sign will be treated as literal text.

Type: string
Required: Yes

Example:

rocketman RenameComputer --computerName %=MODEL:3%-%=BUILDINGNAME:3%-%=LOCALUSERNAME%

Optional Parameters

`--clientId`

Specifies the Jamf API Client ID.

Type: string
Required: Yes
Example:
```
--clientId "YOUR_CLIENT_ID"
```

`--clientSecret`

Specifies the Jamf API Client Secret.

Type: string
Required: Yes
Example:
```
--clientSecret "YOUR_CLIENT_SECRET"
```

`--case`

Specifies how the computer name is formatted:

upper: Converts the name to uppercase.
lower: Converts the name to lowercase.
title: Capitalizes the first letter of each token.
Type: string
Choices: upper, lower, title
Default: None
Example:
```
rocketman RenameComputer --case title
```

`--simulate`

Simulates renaming the computer without applying changes. This is useful for testing the naming scheme.

Type: flag
Default: False
Example:
```
rocketman RenameComputer --simulate
```

`--computerRecordFieldPaths`

Specifies one or more alias:field pairs used to retrieve additional data from Jamf's computer record via the API, which then become available as tokens in the naming scheme. Provide each field as either an alias:field combo or simply as a field path using dot notation (e.g. general.asset_tag).

Note

If no alias is provided (i.e. no colon is present), the token defaults to the last segment of the field path (delimited by a dot) and uppercase.

Important

This requires API credentials to authenticate with Jamf and retrieve the specified fields.

Type: List of strings
Example:
```
--computerRecordFieldPaths general.asset_tag SITE:general.site.name
```
In this example, the retrieved Jamf computer record fields are available as %ASSET_TAG% and %SITE% respectively.

Naming Scheme Tokens

Tokens enclosed in % that are replaced with corresponding values can be formatted to extract substrings:

:n: Uses the first n characters.
:-n: Uses the last n characters.
:=n: Uses the center n characters.
:wX:Y: Extracts Y characters starting at the beginning of the X-th word. For example, %=LOCALFULLNAME:w1:1% gets the first letter of the first word, and %=LOCALFULLNAME:w2:4% gets the first 4 letters of the second word.

If a token cannot be resolved, the tool logs an error and exits.

Flexible Token Substitution for Managed Variables

The tool supports injecting any managed configuration variable directly into the naming scheme using an extended syntax. All such tokens (both local and managed) must include an equals sign (=) immediately after the opening % to be substituted with their corresponding values. Tokens without the equals sign will be interpreted as literal strings.

For example, using:

<key>computerName</key>
<string>%=BUILDINGNAME:3%-%=USERNAME:5%</string>

will extract the first 3 characters of the BUILDINGNAME and the first 5 characters of the USERNAME values. If a variable does not exist, its literal string is used instead.

Local Computer Variables

These tokens are available on every system. Remember: to have these tokens substituted dynamically, they must be prefixed with an equals sign (=) immediately after the opening %. For example:

%=SERIAL%: Device serial number.
%=MAC%: MAC address of the primary network interface.
%=UDID%: Unique Device Identifier.
%=LOCALUSERNAME%: Currently logged-in user’s short username.
%=LOCALFULLNAME%: Currently logged-in user’s full name.
%=MODEL%: Model identifier.
%=ARCH%: Architecture type.

Managed Plist Variables

To access these tokens, deploy a configuration profile with the domain tech.rocketman.computerinventory. For example:

<?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>MANAGEMENTID</key>
    <string>RM123456</string>
    <key>SITENAME</key>
    <string>RocketSite</string>
    <key>SITEID</key>
    <string>RS001</string>
    <key>EMAIL</key>
    <string>[email protected]</string>
    <!--... and so on... -->
  </dict>
</plist>

Once this configuration profile is deployed, the following tokens become available for dynamic substitution (remember to prefix them with the equals sign = when using them in your naming scheme):

%=MANAGEMENTID%: Device management ID assigned by Jamf Pro
%=SITENAME%: Site Name
%=SITEID%: Site ID
%=EMAIL%: Email Address
... and so on...

Note

Data Sourcing Order

The tool populates token values using a cascading fallback:

Local Data: Data is first retrieved from the local system.
Managed Preferences: If a token isn’t found locally, the tool checks the managed preferences plist (tech.rocketman.computerinventory).
Jamf Inventory: Finally, if still unresolved (and if API credentials are provided), data is fetched from Jamf Inventory (including General, Location, and Hardware information).

This layered approach ensures that the most relevant data is used for naming, with graceful fallbacks if certain values are missing.

Redefining Token Values

You can redefine token values using substitution rules stored in a managed plist named tech.rocketman.tokensubstitution (this filename cannot be changed).

Tip

Wildcard matching is supported—use the asterisk (*) as a wildcard at the beginning or end of the string to match any characters.

Important

Rules are processed in order, so ensure that any default or catch-all rule is placed last.

For example, to handle variations in model names (such as Mac mini (M2, 2023) or Mac mini (M1, 2020)) you can define the following:

Managed Substitution Example

<plist version="1.0">
  <dict>
    <key>BUILDINGNAME</key>
    <array>
      <string>Minneapolis:MSP</string>
      <string>Denver:DEN</string>
    </array>
    <key>MODEL</key>
    <array>
      <string>MacBook Pro*:MBP</string>
      <string>MacBook Air*:MBA</string>
      <string>iMac*:IMC</string>
      <string>Mac Mini*:MCM</string>
      <string>*:UNK</string>
    </array>
  </dict>
</plist>

This configuration replaces Minneapolis with MSP and MacBook Pro with MBP in the naming scheme.

Advanced Usage Example

The following example renames the computer using complex formatting and substitution:

rocketman RenameComputer \
  --computerName %=MODEL:3%-%=BUILDINGNAME:3%-%=SERIAL:-4%-%=ASSET_TAG%-%=SITE% \
  --case lower \
  --computerRecordFieldPaths general.asset_tag SITE:general.site.name \
  --simulate

This outputs a simulated name like mbp-fln-1hw9.

Important Notes

Jamf Integration: After computing the name, the tool runs:
```
jamf setComputerName -name $COMPUTERNAME
```
Testing: Use --simulate to verify the naming scheme before applying changes.
Substitution Scope: Substitution only applies to tokens written with the equals sign (e.g. %=VARIABLE%). Tokens without the equals sign are treated as literal text and will not be substituted.

Inspiration

The token substitution method used in this tool is inspired by the approach taken in Setup Manager. More info about their implementation is available in the ConfigurationProfile.md document.