Apple macOS

This page describes the steps for installing and upgrading NXLog Agent on Apple macOS.

Installing NXLog Agent

Follow these steps to install NXLog Agent on Apple macOS. You will need administrator privileges to complete the installation process.

First, download the appropriate NXLog Agent installer file from the NXLog website.

Log in to your account, then click My account at the top of the page.
Under the Downloads > NXLog Agent files tab, choose the correct package for your system.

Table 1. Available NXLog Agent macOS installers

Platform Package

macOS (arm)

nxlog-6.5.9781_macos_arm64.pkg

macOS (x86)

nxlog-6.5.9781_macos_x86_64.pkg

The NXLog Agent installer packages are digitally signed. See Verify the signature of the macOS installer for further details.
Optional: To change the NXLog Agent user and group for the installation, create a /tmp/.nxlog file with the following command. During installation, a new user and a new group will be created using the values specified in this command. They will be used for the User and Group directives in nxlog.conf, and to set ownership of the /opt/nxlog directory. Specifying an already existing user or group is not supported. The created user and group will be deleted when you uninstall NXLog Agent.
```
$ echo 'nxlog2:nxlog2' > /tmp/.nxlog
```

Table 1. Available NXLog Agent macOS installers
Platform	Package
macOS (arm)	nxlog-6.5.9781_macos_arm64.pkg
macOS (x86)	nxlog-6.5.9781_macos_x86_64.pkg

Connecting to NXLog Platform

You can configure NXLog Agent to connect to NXLog Platform automatically. The installation looks for the file /tmp/nxlog_easy_agent with the following settings to configure the Remote Management (xm_admin) instance in the managed.conf file.

NXP_ADDRESS: The NXLog Platform Agent Management URL and port. The installation sets the Host to this value.
NXP_AGENT_LABEL: Sets the agent_label label to this value. You can use this label to Set up automatic agent enrollment.

/tmp/nxlog_easy_agent

NXP_ADDRESS='agents.example.com:5515'
NXP_AGENT_LABEL='new'

Installing interactively

You can execute the installation package by double-clicking it or from the command line.
- Double-click the NXLog Agent package. NXLog Agent installer packages are signed with our developer certificate. However, if you see the following message, go to System Preferences > Security & Privacy and click Open Anyway, then follow the instructions shown by the installer.
  
  "nxlog-6.5.9781_macos.pkg" can’t be opened because it is from an unidentified developer.
- To install the package using the command line, run the following command.
  
  $ sudo installer -pkg nxlog-6.5.9781_macos.pkg -target / Password: installer: Package name is nxlog-6.5.9781-macos-x86 installer: Upgrading at base path / installer: The install was successful.
  
  The target volume is specified by / in the example above. However, the installer supports alternate target volumes.
  
  By default, all NXLog Agent files are copied to /opt/nxlog. To specify a custom installation directory, create an XML file with the following contents, replacing /opt/nxlogcustom with your preferred directory:
  
  choices.xml
  
  <?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"> <array> <dict> <key>attributeSetting</key> <string>/opt/nxlogcustom</string> <key>choiceAttribute</key> <string>customLocation</string> <key>choiceIdentifier</key> <string>com.nxlog.agent</string> </dict> </array> </plist>
  
  Once you create the directory for the alternative installation directory, invoke the command line installer with the path and name of the XML file:
  
  $ sudo mkdir -p /opt/nxlogcustom $ sudo installer -pkg nxlog-6.5.9781_macos.pkg -target / -applyChoiceChangesXML ./choices.xml
The launchd(8) script is installed in /Library/LaunchDaemons/com.nxlog.plist and has the KeepAlive flag set to true (launchd will automatically restart NXLog Agent). NXLog Agent log files are managed by launchd and can be found in /var/log/.
Configure NXLog Agent by editing /opt/nxlog/etc/nxlog.conf.
See Log collection in the NXLog Platform User Guide for more information and configuration examples.
For more details about configuring NXLog Agent to collect logs on macOS, see macOS log sources.

Verify the configuration file syntax.

$ sudo /opt/nxlog/bin/nxlog -v
2017-03-17 08:05:06 INFO configuration OK

To apply your changes, stop NXLog Agent with the following command. The launchd manager will restart the daemon and the new configuration will be loaded.
```
$ sudo launchctl stop com.nxlog
```

To permanently stop NXLog Agent, you must unload the service.

$ sudo launchctl unload -w /Library/LaunchDaemons/com.nxlog.plist

Use the following command to start NXLog Agent and permanently enable the service.
```
$ sudo launchctl load -w /Library/LaunchDaemons/com.nxlog.plist
```

Upgrading NXLog Agent

Follow the installation instructions to upgrade NXLog Agent.

The installation will not modify the existing configuration files unless you enable the FORCE environment variable. However, we recommend backing up the configuration files before starting this process. After the installation is complete, NXLog Agent will restart automatically.

The same user and group will be used for the upgrade as was used for the original installation. See installation user and group above. Changing to a different user and group during an upgrade is not supported.

When upgrading, you can configure new NXLog Platform settings by setting the relevant environment variables in addition to the FORCE environment variable before executing the installer. When forcing a configuration update, the installation backs up the nxlog.conf and managed.conf files before applying the changes.

$ echo "NXP_ADDRESS='agents.example.com:5515' && NXP_AGENT_LABEL='macos' && FORCE='TRUE'" > /tmp/nxlog_easy_agent
$ sudo installer -verbose -dumplog -pkg nxlog-6.5.9781_macos_x86_64.pkg -target /

Currently, if you specify the NXP_ADDRESS and NXP_AGENT_LABEL environment variables without FORCE, the installer does not perform the upgrade and exits without an error message. However, the installer logs the reason in the installation log file.

Changing the installation directory during the upgrade is not supported. If you want to change the installation directory:

Back up the existing configuration files, certificates, and any other files in the installation directory by copying them to another location.
Uninstall NXLog Agent by following the instructions below.
Install NXLog Agent to the new installation directory by following the installation instructions.
Copy the configuration files you backed up to the new installation directory.

Uninstalling NXLog Agent

Follow these steps to uninstall NXLog Agent

Start the uninstaller script as user root.

This will remove custom configuration files, certificates, and any other files in the listed directories. Save these files to another location first if you do not wish to discard them.
```
$ sudo bash /opt/nxlog/bin/uninstaller -y
```
Use the -n switch (instead of -y) if you would like to preserve user data.
Delete user data if you are sure it will not be needed anymore.
```
$ sudo rm -rf /opt/nxlog
```

Follow the steps below to manually uninstall NXLog Agent.

Unload the daemon.

$ sudo launchctl unload /Library/LaunchDaemons/com.nxlog.plist

Delete the nxlog user and group that were created during installation. If you used a custom user/group during the installation, remove those instead. See installation user and group above.
```
$ sudo dscl . -delete "/Groups/nxlog"
$ sudo dscl . -delete "/Users/nxlog"
```
Remove the NXLog Agent files.

This will remove custom configuration files, certificates, and any other files in the listed directories. Save these files to another location first if you do not wish to discard them.
```
$ sudo rm -rf /opt/nxlog /Library/LaunchDaemons/com.nxlog.plist \
              /var/log/nxlog.std* && \
  sudo pkgutil --forget com.nxlog.agent
```