Table of Contents
- Table of Contents
Prequisits & Requirements
root or sudo access will be needed to perform these tasks.
Requirements
- Operating System:
- macOS
- Mac OS X 10.15 or higher
- Linux
- RHEL 8.x or higher
- Ubuntu Server 18.04 (No longer being tested)
- macOS
- Pyhton 3.12 or higher
- RAM: 4 Gig min
- MySQL 8.0.20 or higher
Perquisites
- MySQL installed (must have root password)
- If Installing on Mac OS X, Xcode and command line developer tools need to be installed AND the license agreement needs to have been accepted.
- Python 3.12 installed, if compiling please ensure libffi-devel is installed prior to compiling python.
Linux Packages
The MacPatch server build script will attempt to install a number of required software packages there are a few packages that are recommended that be installed prior to running the build script.
RedHat & CentOS
RedHat & CentOS will require the "Development tools" group install. This group has a number of packages needed to build the MacPatch server.
dnf groupinstall "Development tools"
dnf install epel-release pcre-devel swig
Ubuntu
apt-get install build-essential
Download, Setup and Install
Get Software
mkdir /opt (If Needed)
cd /opt
git clone https://github.com/LLNL/MacPatch.git
Install Software
cd /opt/MacPatch/Scripts
sudo ./MPBuildServer.sh
Setup Database
The database setup script only creates the MacPatch database and the account needed to use the database. It also does some basic database configuration. Tuning the MySQL server is out of scope for this document.
The database script is a sql script. This file will need to be run by the MySQL database root account or an account that has the Grant option.
Please edit the file, by setting the correct variable values for your MacPatch environment. On a standard build, only the default database account (mpdbadm) password needs to be set. Please remeber the mysql account name and password as it will be needed during the server setup.
It's strongly recommended that you delete the sql script once run. The file won't be needed again. Or, at the very least, remove the account password that was set.
cd /opt/MacPatch/Server/conf/scripts/setup
MPDBSetup.sql (must be run on the MySQL server)
Configure Server Software
cd /opt/MacPatch/Server/conf/scripts/setup
sudo ./ServerSetup.py --setup
The setup script will walk you through the following:
- Server keys and default configuration.
- Database settings, use the database account name and password from the database setup step.
- LDAP/Active Directory login settings (optional).
- Database schema & default data. The MacPatch database schema is created and the default data (patch group, software group, client group, agent configuration, etc.) is added.
- First admin account. If no admin account exists you will be asked to create one. Enter an account name (default is "mpadmin") and a password, or leave the password blank to have a strong password generated for you.
- Services to enable.
Important: The admin password is only displayed once, please save it in a secure location. It can not be recovered.
Database Setup & Upgrades
If the database step was skipped during "--setup" or failed (e.g. the database was not reachable), it can be run on its own. This is also used to upgrade the database schema after updating the MacPatch software. It is safe to run more than once, existing data is not changed.
cd /opt/MacPatch/Server/conf/scripts/setup
sudo ./ServerSetup.py --setup-db
To create an additional console admin account from the command line
sudo ./ServerSetup.py --config admin
Note: These commands run as the MacPatch service user (www-data on Linux, _appserver on Mac), there is no need to run them in the console virtual environment.
Start Configured Services
cd /opt/MacPatch/Server/conf/scripts/setup
sudo ./ServerSetup.py --service All --action start
Stop Configured Services
cd /opt/MacPatch/Server/conf/scripts/setup
sudo ./ServerSetup.py --service All --action stop
--
Server Setup & Configuration
The MacPatch server software has now been installed and should be up and running. The server is almost ready for accepting clients. There are a few more server configuration settings which need to be configured.
First Login
Login using the admin account and password created during “ServerSetup.py --setup”. You will need to login for the first time with this account to do all of the setup tasks.
There is no longer a default admin password, and the admin account is no longer stored in the siteconfig.json file. Admin accounts are stored in the MacPatch database with a hashed password.
Once these tasks are completed and other admin accounts have been created, it’s recommended that this account be disabled.
- Go to “Admin -> Accounts”
- Edit the account and set “Enabled” to “No”
If the admin password is lost, it can be reset from the command line. The account is recreated with admin rights and a new password is generated and displayed.
cd /opt/MacPatch/Server/apps/console/scripts
sudo -u www-data /opt/MacPatch/Server/env/console/bin/python3 create_admin_account.py --username mpadmin --force
On Mac use “_appserver” instead of “www-data”.
Upgrading from an older version: If your siteconfig.json still contains a “users” -> “admin” account, it is no longer used. Create a database admin account with “sudo ./ServerSetup.py --config admin” and then remove the “users” section from siteconfig.json.
Server Configuration
Each MacPatch server needs to be added to the environment. The master server is always added automatically.
It is recommended that you login and verify the master server settings. It is common during install that the master server address will be added as localhost or 127.0.0.1. Please make sure that the correct hostname or IP address is set and that "active" is enabled.
- Go to “Admin -> Server -> MacPatch Servers”
- Double Click the row with your server or single click the row and click the “Pencil” button.
Default Patch Group Configuration
A default patch group will be created during install. The name of the default patch group is “Default”. You may use it or create a new one.
To edit the contents for the patch group simply click the “Pencil” icon next to the group name. To add patches click the check boxes to add or subtract patches from the group. When done click the “Save” icon. (Important Step)
- Go to “Patches -> Patch Groups”
- Double Click the row with your server or single click the row and click the “Pencil” button.
Client Agent Configuration
A default agent configuration is added during the install. Please verify the client agent configuration before the client agent is uploaded.
Recommended
- Go to “Admin -> Client Agents -> Configure”
- Set the following 3 properties to be enforced
- MPServerAddress
- MPServerPort
- MPServerSSL
- Verify the “PatchGroup” setting. If you have changed it set it before you upload the client agent.
- Click the save button
- Click the icon in the “Default” column for the default configuration. (Important Step)
- Set MPServerAllowSelfSigned to 1 if your in a test environment and not using a valid SSL vertificate.
Only the default agent configuration will get added to the client agent upon upload.
--
Download & Add Patch Content
Apple patch content will download eventually on it’s own cycle, but for the first time it’s recommended to download it manually.
The Apple Software Update content settings are stored in a json file (/opt/MacPatch/Server/etc/patchloader.json). By default, Apple patches for 10.9 through 10.12 will be processed and supported.
Run the following command via the Terminal on the Master MacPatch server.
Linux
# sudo -u www-data /opt/MacPatch/Server/conf/scripts/MPSUSPatchSync.py
Mac
# sudo -u _appserver /opt/MacPatch/Server/conf/scripts/MPSUSPatchSync.py
To create your own custom patch content please read the "Custom Patch Content" docs.
To use "AutoPkg" to add patch content please read the "AutoPkg patch content" docs.