# Installing the Access Manager Agent on macOS

## Prerequisites

The agent must be able to validate the AMS server certificate. If you are using a self-signed certificate, or a certificate issued from a private CA, you'll need to [add the root certificate](https://support.apple.com/en-au/guide/keychain-access/kyca2431/mac) to the system keychain, and [configure it to be trusted](https://support.apple.com/en-au/guide/keychain-access/kyca11871/mac).

The agent itself runs using launchd, and as it requires access to reset the root password, must be run as the root user.

### OS requirements

The agent requires macOS 13 or later. Packages are available for both Intel and M-series Macs.

## Download the agent

Download the agent for the appropriate architecture from the downloads page, or directly from the package repository using the script below.

```shell
if [[ $(uname -m) == 'arm64' ]]; then 
    curl -fssL https://packages.lithnet.io/macos/access-manager-agent/v3.0/arm64/stable -o ~/accessmanageragent.pkg
else
    curl -fssL https://packages.lithnet.io/macos/access-manager-agent/v3.0/x64/stable -o ~/accessmanageragent.pkg
fi
```

## Validate the package signature

Ensure the package is valid, and has been signed by `Lithnet Pty Ltd (5DK86QQXK3)`

```shell
pkgutil --check-signature ~/accessmanageragent.pkg
```

## Install the agent

You can open the package from finder, or use the `installer` command line tool to install the package

```shell
sudo installer -pkg ~/accessmanageragent.pkg -target /
```

## Configuring the agent

Once the package is installed, it must be configured to talk to your AMS server. You can run the following command to perform an interactive installation

If your device is joined to an Active Directory domain, you can use Windows authentication (kerberos) to authenticate to the AMS server. Otherwise, you will need to create a registration key on the AMS server and use that instead.

```shell
sudo /Library/Application\ Support/Lithnet/AccessManagerAgent/Core/Lithnet.AccessManager.Agent --setup
```

{% hint style="warning" %}
If the hostname provided does not match exactly the `External host name` value configured on the [Host configuration page](https://docs.lithnet.io/ams/help-and-support/application-help-pages/host-configuration-page), the agent will fail to connect to the server
{% endhint %}

To perform a non-interactive installation, use the following command, replacing the server name, and registration key as appropriate. You can generate new registration keys using the AMS configuration tool.

Install the agent using a registration key

```shell
sudo /Library/Application\ Support/Lithnet/AccessManagerAgent/Core/Lithnet.AccessManager.Agent --server ams.lithnet.local --registration-key XXXX
```

Install the agent using Windows authentication (kerberos)

```shell
sudo /Library/Application\ Support/Lithnet/AccessManagerAgent/Core/Lithnet.AccessManager.Agent --server ams.lithnet.local --registration-mode iwa 
```

Check the log using the instructions in the `Viewing the log files` section below to ensure the agent registered correctly.

## Validate agent installation

On the Access Manager server, go to the `Access Manager Agent/Devices` page, and ensure that the devices you installed the agent on have appeared in the device list. If you configured your registration key to require manual approval, you must approve the devices before they can be accessed.

## Secure token support

From v3.0.1500, Access Manager has support for managing the passwords of admin accounts with secure token enabled. Read the [guide on enabling secure token support](https://docs.lithnet.io/ams/help-and-support/advanced-help-topics/enabling-secure-token-support-macos) for more info.

## Restarting the agent

The Lithnet Access Manager Agent runs as a daemon using launchd. You can use standard launchd commands to start, stop and restart the agent.

```shell
sudo launchctl kickstart -k system/io.lithnet.accessmanager.agent
```

## Uninstalling the agent

You can use the uninstallation script provided to remove the agent from the computer.

```shell
sudo /Library/Application\ Support/Lithnet/AccessManagerAgent/Core/uninstall.sh
```

## Viewing log files

The agent logs can be viewed using the `Console` app, or using the command line

To show all events in the log use the following command

```shell
tail /Library/Logs/Lithnet/AccessManagerAgent/LithnetAccessManagerAgent.log
```

To show a live stream of log messages use the following command

```shell
tail -f /Library/Logs/Lithnet/AccessManagerAgent/LithnetAccessManagerAgent.log
```

## File locations

The agent creates and uses the following files and folders.

`/Library/Application Support/Lithnet/AccessManagerAgent/Configuration/LithnetAccessManagerAgent.conf` - The main configuration file for the application. This contains the AMS server name and other settings relevant to the application.

`/Library/Application Support/Lithnet/AccessManagerAgent/Configuration/LithnetAccessManagerAgent.state` - This contains information used by the agent to store its current state information. This file should not be modified. It is generated by the app when it is run, and is not part of the installation package.

`/Library/Application Support/Lithnet/AccessManagerAgent/Core` - This directory contains the application binary files.

`/Library/Logs/Lithnet/AccessManagerAgent/` - This directory contains the agent log files.

`/Library/LaunchDaemons/io.lithnet.accessmanager.agent.plist` - The launchd entry for the agent, symlinked from the application directory.