Apple macOS

This topic describes the steps to install and upgrade NXLog on Apple macOS.

Installing

To install NXLog under macOS, follow the steps below. You will need administrator privileges to complete the installation process.

First, download the appropriate NXLog install package from the NXLog website.

  1. Log in to your account, then click My account at the top of the page.

  2. Under the Downloads > NXLog Enterprise Edition files tab, choose the correct package for your system.

    Table 1. Available macOS Packages
    Platform Package

    macOS (arm)

    nxlog-5.5.7550_macos_arm64.pkg

    macOS (x86)

    nxlog-5.5.7550_macos_x86_64.pkg

    The NXLog installer packages are digitally signed. For more details about package verification, see the Signature Verification on macOS section in the User Guide.

  1. Optional: To change the NXLog 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 User and Group directives in nxlog.conf, and for the ownership of some subdirectories under the installation directory. Specifying an already existing user or group is not supported. The created user and group will be deleted on NXLog removal.

    $ echo 'nxlog2:nxlog2' > /tmp/.nxlog
  2. Install the NXLog package. You can do the installation interactively or with the command line installer.

    • To install interactively, double-click the NXLog package.

      As of version 4.5 the installer should be signed with our developer certificate. If you see the following message with an earlier version, go to System Preferences > Security & Privacy and click Open Anyway, then follow the instructions shown by the installer.

      "nxlog-5.5.7550_macos.pkg" can’t be opened because it is from an unidentified developer.

      Allow NXLog to launch the installer
    • To install the package using the command line installer, run the following command.

      $ sudo installer -pkg nxlog-5.5.7550_macos.pkg -target /
      Password:
      installer: Package name is nxlog-5.5.7550-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 files are placed under /opt/nxlog. To specify a custom installation directory, create an XML file with the following contents (replace /opt/nxlogcustom with the 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 the directory for the alternate installation location has been created, invoke the command line installer with the path and name of the XML file in order to deploy the customized installation:

      $ sudo mkdir -p /opt/nxlogcustom
      $ sudo installer -pkg nxlog-5.5.7550_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). NXLog log files are managed by launchd and can be found in /var/log/.

  3. Configure NXLog by editing /opt/nxlog/etc/nxlog.conf. General information about configuring NXLog can be found in Configuration. For more details about configuring NXLog to collect logs on macOS, see the Apple macOS summary.

  4. Verify the configuration file syntax.

    $ sudo /opt/nxlog/bin/nxlog -v
    2017-03-17 08:05:06 INFO configuration OK
  5. To apply your changes, stop NXLog with the following command. The launchd manager will restart the daemon and the new configuration will be loaded.

    $ sudo launchctl stop com.nxlog
  6. To permanently stop NXLog, the service must be unloaded.

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

Upgrading

To upgrade NXLog, follow the installation instructions.

The installation script will not modify the existing configuration files, however it is recommended to make a backup of the configuration files before starting this process. After the installation has completed, NXLog will restart automatically.

The same user and group will be used for the upgrade that were used for the original installation (see installation step 3 above). Changing to a different user and/or group during upgrade is not supported.

Changing the installation directory during the upgrade is not supported. To properly change the installation directory:

  1. Backup existing configuration files, certificates, and any other files in the existing installation directory by copying these files to another location.

  2. Uninstall NXLog by following the instructions below.

  3. Install NXLog to the new installation directory by following the installation instructions.

  4. Copy files from the saved location to the new installation directory.

Uninstalling

To properly uninstall NXLog, follow these steps.

  1. 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.
  2. Delete user data if you are sure it will not be needed anymore.

    $ sudo rm -rf /opt/nxlog

To manually uninstall NXLog, follow these steps below.

  1. Unload the daemon.

    $ sudo launchctl unload /Library/LaunchDaemons/com.nxlog.plist
  2. Delete the nxlog user and group that were created during installation. If a non-default user/group were used during installation (see installation step 3 above), remove those instead.

    $ sudo dscl . -delete "/Groups/nxlog"
    $ sudo dscl . -delete "/Users/nxlog"
  3. Remove NXLog 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