Skip to main content

Technical Bulletin 2026-004: Recover FileWave Client on macOS

Scope: This recovery procedure applies to affected FileWave Client builds on managed macOS devices in the supported FileWave 16.2.x, 16.3.x, and 16.4.x release lines. Corrected same-version packages have been rebuilt for the affected Client versions listed below. Installing a rebuilt package does not change the Client version, so version alone does not show whether recovery has been completed. FileWave Client release lines earlier than 16.2.x also use the previous certificate and will be affected, but corrected builds are not available for those unsupported releases. iOS, iPadOS, tvOS, visionOS, Windows, Android, ChromeOS, and Linux are not affected.

Important: Do not run the recovery command until the corrected macOS FileWave Client package has been prepared in FileWave Central using the version-specific path in Step 1. Running the command first can redeploy the affected package.

Background

Beginning July 30, 2026, macOS may block FileWave Client on managed Macs and warn that the software may be malicious.

This is a code-signing certificate issue, not malicious FileWave software or a broader security compromise. As part of a planned transition coordinated with Apple, FileWave closed its original Apple Developer account. Kiosk-related code distributed with FileWave Client for macOS had not been moved to the replacement signing certificate before that account was closed. macOS treats the affected code as untrusted and may block FileWave Client.

Because Apple MDM communication is independent of the FileWave Client connection, the FileWave Server can use the existing MDM channel to install a corrected client package on affected devices.

Does this recovery procedure apply?

Corrected same-version packages are available for these affected FileWave Client versions:

Client release line Client versions with corrected same-version rebuilds
16.2.x 16.2.1, 16.2.2, 16.2.3, 16.2.4, and 16.2.5
16.3.x 16.3.1, 16.3.2, and 16.3.4
16.4.x 16.4.0

This procedure applies to Macs that still have an original affected package from this list. A recovered Mac continues to report the same Client version, so use your recovery records rather than the version alone to determine whether it has received the corrected package.

Package preparation by FileWave Server version

Where you prepare the corrected package depends on the FileWave Server version. The package you prepare must also be the intended recovery package for the Client version group you target. Use the row that matches your Server:

FileWave Server version Required action
Earlier than 16.2.x No supported corrected Client package is available for these releases. Contact FileWave Support to plan an upgrade to a supported release. Do not proceed until a supported corrected Client package is available for the environment.
16.2.x or 16.3.x No FileWave Server or component upgrade is required. At FileWave Custom Packages, generate the rebuilt package that matches the affected Client version you are recovering. Upload it in FileWave Central, then continue with the recovery script.
16.4.0 No FileWave Server or component upgrade is required. In FileWave Central, rebuild the macOS client package as version 16.4.0, then continue with the recovery script so the Server pushes the refreshed same-version package. Do not use custom.filewave.com for this path.

Before you begin

You need:

  • Administrative shell access to the FileWave Server for a self-managed environment. FileWave Hosted customers do not need shell access; FileWave Support performs the Server-side commands.
  • A working Apple MDM connection for the affected Macs.
  • The attached send_reinstall_fwcld_apn.py recovery command. FileWave Hosted customers do not need to download this file; FileWave Support installs it on the Hosted Server.
  • A corrected macOS FileWave Client package prepared through the version-specific workflow in Step 1.
  • FileWave Central inventory identifying Macs running one of the affected Client versions listed above. Because corrected packages retain the same version, use your recovery records to exclude Macs that have already received the rebuilt package.
  • The serial number of each target Mac, or a serial-number list, unless you deliberately intend to target every managed Mac.
  • Confirmation that no other administrator is running this recovery command. Run only one instance at a time.

FileWave Hosted Server checkpoint: Hosted customers can prepare the corrected package in FileWave Central using the Step 1 path for their Server version. No Server upgrade is required for FileWave Server 16.4.0. After the applicable package preparation is complete, FileWave Support must perform the Server-side script installation, dry run, and recovery execution. See the information box in Step 2.

1. Prepare the corrected macOS client package

Use the path that matches the FileWave Server version. The corrected package must be ready in FileWave Central before you install or run the recovery command.

FileWave Server 16.2.x or 16.3.x

No FileWave Server or other component upgrade is required for this path.

  1. Open FileWave Custom Packages and generate a new macOS FileWave Client installer for your environment.
  2. Confirm that the rebuilt package matches the affected Client version you intend to recover. Do not reuse a previously generated or cached installer.
  3. In FileWave Central, open Preferences → Mobile → macOS.
  4. Upload the corrected installer and save the preference change.

If the environment contains more than one affected Client version, prepare and recover one matching version group at a time. Before each recovery run, confirm that the package configured in FileWave Central matches the Macs you are about to target.

FileWave Server 16.4.0

No FileWave Server or other component upgrade is required. Do not use custom.filewave.com with a FileWave 16.4 Server.

  1. In FileWave Central, open Preferences → Mobile → macOS and select Build macOS client package. This integrated workflow is documented under FileWave Server 16.4 or later.
  2. Wait for the build to complete and confirm that the package is ready for enrollment as FileWave Client 16.4.0. Rebuilding refreshes the corrected package but does not change its version number.

FileWave Central macOS pane showing the rebuilt FileWave Client 16.4.0 package and expanded settings

If Central reports that the package configuration already exists

FileWave Central 16.4.0 may report “A package with the same configuration already exists.” when you select Build macOS client package.

FileWave Central message stating that a package with the same configuration already exists

  1. Select OK, then select Show settings.
  2. Record the current value of a package setting such as Heartbeat Interval, then temporarily change that value.
  3. Select Build macOS client package again and wait for the build to finish.
  4. Restore the original setting value and build the package once more. Wait for that final build to finish before continuing.

Do not continue to Step 2 until the corrected package is configured in FileWave Central. A corrected package rebuilt on FileWave Server 16.4.0 will still display version 16.4.0.

2. Install the recovery command on the FileWave Server

FileWave Hosted customers: After the applicable package-preparation path in Step 1 is complete, identify the intended target devices and contact FileWave Support. Reference Technical Bulletin 2026-004. FileWave Support must install and run the recovery command on the Hosted Server, including the dry run in Step 3 and the approved execution in Step 4. Review the dry-run device count and serial numbers with Support before the command is executed. Afterward, complete the Validate recovery checks in this article.

For a self-managed FileWave Server, run the following one-line command on the Server. It works on macOS and Debian 12 or 13. The command confirms that the FileWave Server management entry point exists, downloads the attached script over HTTPS, verifies its SHA-256 checksum using sha256sum or shasum, determines the root account's platform-specific primary group (wheel on macOS or root on Debian), creates the custom-command directory if needed, and installs the file with the correct ownership, permissions, path, and filename only after the checksum matches.

sudo sh -c 'set -eu; url="https://kb.filewave.com/attachments/544"; expected="1c16f0375f6c67749bc5012b92e809c6d0a2f2c55e384d1a77bcfd139266efc2"; dest=base="/usr/local/filewave/django/django"; manage="$base/manage.pyc"; command_dir="$base/filewave/management/commands/commands"; dest="$command_dir/send_reinstall_fwcld_apn.py"; [ -f "$manage" ] || { printf "FileWave Server management entry point not found: %s\n" "$manage" >&2; exit 1; }; tmp=$(mktemp); cleanup() { rm -f "$tmp"; }; trap cleanup EXIT HUP INT TERM; command -v curl >/dev/null 2>&1 || { echo "curl is required." >&2; exit 1; }; curl -fsSL --proto "=https" --tlsv1.2 "$url" -o "$tmp"; if command -v sha256sum >/dev/null 2>&1; then actual=$(sha256sum "$tmp"); elif command -v shasum >/dev/null 2>&1; then actual=$(shasum -a 256 "$tmp"); else echo "sha256sum or shasum is required." >&2; exit 1; fi; actual=${actual%% *}; [ "$actual" = "$expected" ] || { printf "Checksum mismatch: expected %s, got %s\n" "$expected" "$actual" >&2; exit 1; }; root_group=$(id -gn root); install -d -o root -g "$root_group" -m 0755 "$command_dir"; install -o root -g "$root_group" -m 0644 "$tmp" "$dest"; printf "Installed %s (SHA-256 %s)\n" "$dest" "$actual"'

If you are already signed in as root on a Debian server where sudo is not installed, omit the leading sudo. The command exits without installing the file if the download fails or the checksum does not match. A successful run prints the installed path and verified SHA-256 value.

3. Preview the target devices

Run a dry run before queuing anything. A dry run lists matching devices but does not create commands or send APNs.

Targeting check: The recovery command does not filter Macs by their current FileWave Client version. Compare the dry-run serial numbers with FileWave Central inventory and confirm that the package currently configured in Preferences → Mobile → macOS is the intended recovery package for every target Mac. Use your recovery records to exclude Macs that have already received the corrected package.

Preview every managed MDM Mac

sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc send_reinstall_fwcld_apn --dry-run --all

Preview a single Mac by serial number

sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc send_reinstall_fwcld_apn --dry-run --serial SERIAL_NUMBER

Preview Macs from a serial-number file

Create a text file containing one serial number per line, then run:

sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc send_reinstall_fwcld_apn --dry-run --serial-file /path/to/serials.txt

Review the output and confirm that the device count and serial numbers match your intended scope.

4. Queue the corrected client installation

Target the smallest scope that covers the affected Macs. For staged recovery, use --serial or --serial-file and work through the fleet in matching version groups. If the fleet contains more than one affected Client version, configure the matching rebuilt package and complete recovery for one version group before preparing the next package. Reserve --all for when every returned Mac should receive the one package currently configured in FileWave Central, and only after validating the dry-run results:

--all deploys the one package currently configured in FileWave Central to every managed MDM Mac returned by the command. This can include Macs running another Client version or Macs that have already received a corrected package. Use it only when deploying that configured package across the full returned scope is deliberate.

sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc send_reinstall_fwcld_apn --all

To target a single Mac:

sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc send_reinstall_fwcld_apn --serial SERIAL_NUMBER

To target a list of Macs:

sudo /usr/local/filewave/python/bin/python /usr/local/filewave/django/manage.pyc send_reinstall_fwcld_apn --serial-file /path/to/serials.txt

Use only one targeting option at a time. The script requires --all, --serial, or --serial-file so that it cannot target devices accidentally without an explicit scope.

What the command does

The command:

  1. Finds managed macOS devices matching the selected scope.
  2. Queues an InstallApplication command for the FileWave Client package currently configured under Preferences → Mobile → macOS.
  3. Commits all queued commands to the database.
  4. Sends an APN to each selected device through its existing Apple MDM connection.

APNs are sent one device at a time with a brief pause between devices. Large fleets can take significant time to process. If an APN fails for a device, the installation command remains queued and can be received at that device's next natural MDM check-in.

Validate recovery

After the command completes:

  1. Confirm the output reports the expected number of queued commands.
  2. Review any reported APN failures. Those devices retain their queued installation command and can receive it at their next natural MDM check-in.
  3. Allow online devices time to receive the MDM command and install the corrected package.
  4. In FileWave Central, confirm that recovered Macs resume normal FileWave Client check-ins and continue to report the expected Client version for the package you rebuilt. Do not expect the Client version number to change.
  5. On representative Macs, confirm FileWave Client starts normally and the macOS blocking warning no longer appears.
  6. If your organization uses Kiosk, confirm Kiosk opens normally on a representative device.

Troubleshooting

  • No matching device. Verify the serial number, confirm the device is macOS, and confirm it is enrolled through Apple MDM.
  • No InstallApplication commands queued. The matching device may not have a linked MDM client. Confirm its MDM enrollment and contact FileWave Support if needed.
  • macOS reports an INS@...: No such file or directory install path. This is the temporary filename used internally by macOS install; it means the destination command directory did not exist. Rerun the current one-line installation command, which verifies the FileWave Server management entry point and creates the command directory before installing the file.
APN failures are reported. The installation command is already queued. Allow the device to check in naturally or contact FileWave Support for help with the MDM push. Do not repeatedly run the recovery command without first reviewing the device's command queue. The blocking warning persists after recovery. Confirm that the package configured under Preferences → Mobile → macOS is the corrected installer, not a cached or previously generated package. A recovered Mac still reports the same Client version. This is expected. Each rebuilt corrected package retains its original version; confirm recovery through normal Client check-ins, normal Client and Kiosk operation, and the absence of the macOS blocking warning. You ran the command before preparing the corrected package. Stop and contact FileWave Support before continuing.

Optional cleanup

After all affected Macs have recovered and you no longer need the command, remove the management-command file from the FileWave Server:

sudo rm /usr/local/filewave/django/filewave/management/commands/send_reinstall_fwcld_apn.py

Keep the downloaded attachment with your incident records if your organization requires it.

Back to top