In this post, I am going to show you how to run Orchestrator on FreeBSD. The instructions have been tested in FreeBSD 11.3 but the general steps should apply to other versions as well.
At the time of this writing, Orchestrator doesn’t provide FreeBSD binaries, so we will need to compile it.
Preparing the Environment
The first step is to install the prerequisites. Let’s start by installing git:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 | [vagrant@freebsd ~]$ sudo pkg update Updating FreeBSD repository catalogue... Fetching meta.txz: 100% 944 B 0.9kB/s 00:01 Fetching packagesite.txz: 100% 6 MiB 492.3kB/s 00:13 Processing entries: 100% FreeBSD repository update completed. 31526 packages processed. All repositories are up to date. [vagrant@freebsd ~]$ sudo pkg install git Updating FreeBSD repository catalogue... FreeBSD repository is up to date. All repositories are up to date. New version of pkg detected; it needs to be installed first. The following 1 package(s) will be affected (of 0 checked): Installed packages to be UPGRADED: pkg: 1.12.0 -> 1.12.0_1 Number of packages to be upgraded: 1 3 MiB to be downloaded. Proceed with this action? [y/N]: y [1/1] Fetching pkg-1.12.0_1.txz: 100% 3 MiB 324.6kB/s 00:11 Checking integrity... done (0 conflicting) [1/1] Upgrading pkg from 1.12.0 to 1.12.0_1... [1/1] Extracting pkg-1.12.0_1: 100% Updating FreeBSD repository catalogue... FreeBSD repository is up to date. All repositories are up to date. The following 30 package(s) will be affected (of 0 checked): New packages to be INSTALLED: git: 2.25.0 p5-CGI: 4.45 p5-HTML-Parser: 3.72 p5-HTML-Tagset: 3.20_1 perl5: 5.30.1 expat: 2.2.8 p5-IO-Socket-SSL: 2.066 p5-Mozilla-CA: 20180117 p5-Net-SSLeay: 1.88 p5-IO-Socket-INET6: 2.72_1 p5-Socket6: 0.29 p5-Authen-SASL: 2.16_1 p5-GSSAPI: 0.28_1 p5-Digest-HMAC: 1.03_1 python37: 3.7.6 readline: 8.0.1 libffi: 3.2.1_3 p5-Error: 0.17029 pcre: 8.43_2 p5-subversion: 1.13.0 utf8proc: 2.4.0 subversion: 1.13.0 serf: 1.3.9_4 apr: 1.7.0.1.6.1 gdbm: 1.18.1_1 db5: 5.3.28_7 sqlite3: 3.30.1,1 liblz4: 1.9.2_1,1 p5-Term-ReadKey: 2.38_1 cvsps: 2.1_2 Number of packages to be installed: 30 The process will require 297 MiB more space. 57 MiB to be downloaded. Proceed with this action? [y/N]: y [1/30] Fetching git-2.25.0.txz: 100% 6 MiB 199.8kB/s 00:29 [2/30] Fetching p5-CGI-4.45.txz: 100% 154 KiB 158.1kB/s 00:01 [3/30] Fetching p5-HTML-Parser-3.72.txz: 100% 80 KiB 81.8kB/s 00:01 [4/30] Fetching p5-HTML-Tagset-3.20_1.txz: 100% 12 KiB 12.0kB/s 00:01 [5/30] Fetching perl5-5.30.1.txz: 100% 14 MiB 242.0kB/s 01:02 [6/30] Fetching expat-2.2.8.txz: 100% 124 KiB 127.2kB/s 00:01 ... [30/30] Fetching cvsps-2.1_2.txz: 100% 43 KiB 44.1kB/s 00:01 Checking integrity... done (0 conflicting) [1/30] Installing readline-8.0.1... [1/30] Extracting readline-8.0.1: 100% [2/30] Installing expat-2.2.8... [2/30] Extracting expat-2.2.8: 100% [3/30] Installing gdbm-1.18.1_1... [3/30] Extracting gdbm-1.18.1_1: 100% [4/30] Installing db5-5.3.28_7... [4/30] Extracting db5-5.3.28_7: 100% [5/30] Installing perl5-5.30.1... [5/30] Extracting perl5-5.30.1: 100% ... [30/30] Installing git-2.25.0... ===> Creating groups. Creating group 'git_daemon' with gid '964'. ===> Creating users Creating user 'git_daemon' with uid '964'. [30/30] Extracting git-2.25.0: 100% ===== Message from perl5-5.30.1: -- The /usr/bin/perl symlink has been removed starting with Perl 5.20. For shebangs, you should either use: #!/usr/local/bin/perl or #!/usr/bin/env perl The first one will only work if you have a /usr/local/bin/perl, the second will work as long as perl is in PATH. ===== Message from apr-1.7.0.1.6.1: -- The Apache Portable Runtime project removed support for FreeTDS with version 1.6. Users requiring MS-SQL connectivity must migrate configurations to use the added ODBC driver and FreeTDS' ODBC features. ===== Message from python37-3.7.6: -- Note that some standard Python modules are provided as separate ports as they require additional dependencies. They are available as: py37-gdbm databases/py-gdbm@py37 py37-sqlite3 databases/py-sqlite3@py37 py37-tkinter x11-toolkits/py-tkinter@py37 ===== Message from git-2.25.0: -- If you installed the GITWEB option please follow these instructions: In the directory /usr/local/share/examples/git/gitweb you can find all files to make gitweb work as a public repository on the web. All you have to do to make gitweb work is: 1) Please be sure you're able to execute CGI scripts in /usr/local/share/examples/git/gitweb. 2) Set the GITWEB_CONFIG variable in your webserver's config to /usr/local/etc/git/gitweb.conf. This variable is passed to gitweb.cgi. 3) Restart server. If you installed the CONTRIB option please note that the scripts are installed in /usr/local/share/git-core/contrib. Some of them require other ports to be installed (perl, python, etc), which you may need to install manually. |
We also need the go and rsync packages in order to compile:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 | [vagrant@freebsd ~/orchestrator]$ sudo pkg install go Updating FreeBSD repository catalogue... FreeBSD repository is up to date. All repositories are up to date. The following 1 package(s) will be affected (of 0 checked): New packages to be INSTALLED: go: 1.13.7,1 Number of packages to be installed: 1 The process will require 266 MiB more space. 75 MiB to be downloaded. Proceed with this action? [y/N]: y [1/1] Fetching go-1.13.7,1.txz: 100% 75 MiB 245.2kB/s 05:22 Checking integrity... done (0 conflicting) [1/1] Installing go-1.13.7,1... [1/1] Extracting go-1.13.7,1: 100% [vagrant@freebsd ~/orchestrator]$ sudo pkg install rsync Updating FreeBSD repository catalogue... FreeBSD repository is up to date. All repositories are up to date. The following 2 package(s) will be affected (of 0 checked): New packages to be INSTALLED: rsync: 3.1.3_1 libiconv: 1.14_11 Number of packages to be installed: 2 The process will require 3 MiB more space. 916 KiB to be downloaded. Proceed with this action? [y/N]: y [1/2] Fetching rsync-3.1.3_1.txz: 100% 308 KiB 315.9kB/s 00:01 [2/2] Fetching libiconv-1.14_11.txz: 100% 608 KiB 311.1kB/s 00:02 Checking integrity... done (0 conflicting) [1/2] Installing libiconv-1.14_11... [1/2] Extracting libiconv-1.14_11: 100% [2/2] Installing rsync-3.1.3_1... [2/2] Extracting rsync-3.1.3_1: 100% |
Compiling Orchestrator
Now it is time to clone the repository from GitHub:
1 2 3 4 5 6 7 8 | [vagrant@freebsd ~]$ git clone https://github.com/github/orchestrator.git Cloning into 'orchestrator'... remote: Enumerating objects: 56, done. remote: Counting objects: 100% (56/56), done. remote: Compressing objects: 100% (44/44), done. remote: Total 28442 (delta 17), reused 32 (delta 10), pack-reused 28386 Receiving objects: 100% (28442/28442), 15.52 MiB | 3.60 MiB/s, done. Resolving deltas: 100% (18006/18006), done. |
The next step is to compile Orchestrator. According to the manual, we need to run script/build as follows:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 | [vagrant@freebsd ~]$ cd orchestrator/ [vagrant@freebsd ~/orchestrator]$ script/build go version go1.13.7 freebsd/amd64 found in : Go Binary: /usr/local/bin/go ++ rm -rf .gopath ++ mkdir -p .gopath/src/github.com/github ++ ln -s /home/vagrant/orchestrator .gopath/src/github.com/github/orchestrator ++ export GOPATH=/home/vagrant/orchestrator/.gopath:/home/vagrant/orchestrator/.vendor ++ GOPATH=/home/vagrant/orchestrator/.gopath:/home/vagrant/orchestrator/.vendor + mkdir -p bin + bindir=/home/vagrant/orchestrator/bin + scriptdir=/home/vagrant/orchestrator/script ++ git rev-parse HEAD + version=548265494b3107ca2581d6ccee059e062a759b77 ++ git describe --tags --always --dirty + describe=v3.1.4-2-g54826549 + export GOPATH=/home/vagrant/orchestrator/.gopath + GOPATH=/home/vagrant/orchestrator/.gopath + cd .gopath/src/github.com/github/orchestrator + go build -i -o /home/vagrant/orchestrator/bin/orchestrator -ldflags '-X main.AppVersion=548265494b3107ca2581d6ccee059e062a759b77 -X main.BuildDescribe=v3.1.4-2-g54826549' ./go/cmd/orchestrator/main.go + rsync -qa ./resources /home/vagrant/orchestrator/bin/ |
Installation
Now, we have to move the compiled binary (and the additional files) to the final destination directory. In this case, I chose to use /usr/local/orchestrator.
1 2 3 | [vagrant@freebsd ~/orchestrator]$ sudo mkdir -p /usr/local/orchestrator [vagrant@freebsd ~/orchestrator]$ mv /home/vagrant/orchestrator/bin/orchestrator /usr/local/orchestrator/ [vagrant@freebsd ~/orchestrator]$ mv /home/vagrant/orchestrator/bin/resources /usr/local/orchestrator/ |
We also need to create both an init script and operating system user for Orchestrator, for example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 | [vagrant@freebsd ~/orchestrator]$ sudo pw useradd orchestrator -s /usr/sbin/nologin [vagrant@freebsd ~/orchestrator]$ sudo vi /usr/local/etc/rc.d/orchestrator #!/bin/sh # PROVIDE: orchestrator # REQUIRE: LOGIN # KEYWORD: shutdown # # Add the following line to /etc/rc.conf to enable orchestrator: # orchestrator_enable (bool): Set to "NO" by default. # Set it to "YES" to enable MySQL. # orchestrator_dir (str): Default to "/usr/local/orchestrator" # Base configuration directory. # orchestrator_pidfile (str): Custom PID file path and name. # Default to "${orchestrator_dbdir}/${hostname}.pid". # orchestrator_args (str): Custom additional arguments to be passed # to orchestrator (default --verbose http). # . /etc/rc.subr name="orchestrator" rcvar=orchestrator_enable load_rc_config $name : ${orchestrator_enable="NO"} : ${orchestrator_dir="/usr/local/orchestrator"} : ${orchestrator_args="--verbose http"} orchestrator_user="orchestrator" : ${hostname:=`/bin/hostname`} pidfile=${orchestrator_pidfile:-"${orchestrator_dir}/${hostname}.pid"} procname="/usr/local/orchestrator/orchestrator" command="/usr/sbin/daemon" command_args="-p ${pidfile} ${orchestrator_dir}/orchestrator ${orchestrator_args} >> /var/log/${name}.log 2>&1" run_rc_command "$1" |
We shouldn’t forget to set the proper permissions for the init script and the orchestrator directory:
1 2 | [vagrant@freebsd ~/orchestrator]$ sudo chmod +x /usr/local/etc/rc.d/orchestrator [vagrant@freebsd ~/orchestrator]$ sudo chown -R orchestrator: /usr/local/orchestrator |
Now let’s create a sample configuration file using the template available in GitHub:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 | [vagrant@freebsd ~/orchestrator]$ sudo vi /etc/orchestrator.conf.json { "Debug": true, "EnableSyslog": false, "ListenAddress": ":3000", "MySQLTopologyUser": "orc_client_user", "MySQLTopologyPassword": "orc_client_password", "MySQLTopologyCredentialsConfigFile": "", "MySQLTopologySSLPrivateKeyFile": "", "MySQLTopologySSLCertFile": "", "MySQLTopologySSLCAFile": "", "MySQLTopologySSLSkipVerify": true, "MySQLTopologyUseMutualTLS": false, "BackendDB": "sqlite", "SQLite3DataFile": "/usr/local/orchestrator/orchestrator.sqlite3", "DefaultInstancePort": 3306, "DiscoverByShowSlaveHosts": true, "InstancePollSeconds": 5, "DiscoveryIgnoreReplicaHostnameFilters": [ "a_host_i_want_to_ignore[.]example[.]com", ".*[.]ignore_all_hosts_from_this_domain[.]example[.]com" ], "UnseenInstanceForgetHours": 240, "SnapshotTopologiesIntervalHours": 0, "InstanceBulkOperationsWaitTimeoutSeconds": 10, "HostnameResolveMethod": "default", "MySQLHostnameResolveMethod": "@@hostname", "SkipBinlogServerUnresolveCheck": true, "ExpiryHostnameResolvesMinutes": 60, "RejectHostnameResolvePattern": "", "ReasonableReplicationLagSeconds": 10, "ProblemIgnoreHostnameFilters": [], "VerifyReplicationFilters": false, "ReasonableMaintenanceReplicationLagSeconds": 20, "CandidateInstanceExpireMinutes": 60, "AuditLogFile": "", "AuditToSyslog": false, "RemoveTextFromHostnameDisplay": ".mydomain.com:3306", "ReadOnly": false, "AuthenticationMethod": "", "HTTPAuthUser": "", "HTTPAuthPassword": "", "AuthUserHeader": "", "PowerAuthUsers": [ "*" ], "ClusterNameToAlias": { "127.0.0.1": "test suite" }, "SlaveLagQuery": "", "DetectClusterAliasQuery": "SELECT SUBSTRING_INDEX(@@hostname, '.', 1)", "DetectClusterDomainQuery": "", "DetectInstanceAliasQuery": "", "DetectPromotionRuleQuery": "", "DataCenterPattern": "[.]([^.]+)[.][^.]+[.]mydomain[.]com", "PhysicalEnvironmentPattern": "[.]([^.]+[.][^.]+)[.]mydomain[.]com", "PromotionIgnoreHostnameFilters": [], "DetectSemiSyncEnforcedQuery": "", "ServeAgentsHttp": false, "AgentsServerPort": ":3001", "AgentsUseSSL": false, "AgentsUseMutualTLS": false, "AgentSSLSkipVerify": false, "AgentSSLPrivateKeyFile": "", "AgentSSLCertFile": "", "AgentSSLCAFile": "", "AgentSSLValidOUs": [], "UseSSL": false, "UseMutualTLS": false, "SSLSkipVerify": false, "SSLPrivateKeyFile": "", "SSLCertFile": "", "SSLCAFile": "", "SSLValidOUs": [], "URLPrefix": "", "StatusEndpoint": "/api/status", "StatusSimpleHealth": true, "StatusOUVerify": false, "AgentPollMinutes": 60, "UnseenAgentForgetHours": 6, "StaleSeedFailMinutes": 60, "SeedAcceptableBytesDiff": 8192, "PseudoGTIDPattern": "", "PseudoGTIDPatternIsFixedSubstring": false, "PseudoGTIDMonotonicHint": "asc:", "DetectPseudoGTIDQuery": "", "BinlogEventsChunkSize": 10000, "SkipBinlogEventsContaining": [], "ReduceReplicationAnalysisCount": true, "FailureDetectionPeriodBlockMinutes": 60, "RecoveryPeriodBlockSeconds": 3600, "RecoveryIgnoreHostnameFilters": [], "RecoverMasterClusterFilters": [ "_master_pattern_" ], "RecoverIntermediateMasterClusterFilters": [ "_intermediate_master_pattern_" ], "OnFailureDetectionProcesses": [ "echo 'Detected {failureType} on {failureCluster}. Affected replicas: {countSlaves}' >> /tmp/recovery.log" ], "PreFailoverProcesses": [ "echo 'Will recover from {failureType} on {failureCluster}' >> /tmp/recovery.log" ], "PostFailoverProcesses": [ "echo '(for all types) Recovered from {failureType} on {failureCluster}. Failed: {failedHost}:{failedPort}; Successor: {successorHost}:{successorPort}' >> /tmp/recovery.log" ], "PostUnsuccessfulFailoverProcesses": [], "PostMasterFailoverProcesses": [ "echo 'Recovered from {failureType} on {failureCluster}. Failed: {failedHost}:{failedPort}; Promoted: {successorHost}:{successorPort}' >> /tmp/recovery.log" ], "PostIntermediateMasterFailoverProcesses": [ "echo 'Recovered from {failureType} on {failureCluster}. Failed: {failedHost}:{failedPort}; Successor: {successorHost}:{successorPort}' >> /tmp/recovery.log" ], "CoMasterRecoveryMustPromoteOtherCoMaster": true, "DetachLostSlavesAfterMasterFailover": true, "ApplyMySQLPromotionAfterMasterFailover": true, "PreventCrossDataCenterMasterFailover": false, "MasterFailoverDetachSlaveMasterHost": false, "MasterFailoverLostInstancesDowntimeMinutes": 0, "PostponeSlaveRecoveryOnLagMinutes": 0, "OSCIgnoreHostnameFilters": [], "GraphiteAddr": "", "GraphitePath": "", "GraphiteConvertHostnameDotsToUnderscores": true } |
Finally, let’s configure Orchestrator to start at boot time, and start the service:
1 2 3 | [vagrant@freebsd ~/orchestrator]$ sudo echo 'orchestrator_enable="YES"' >> /etc/rc.conf [vagrant@freebsd ~/orchestrator]$ sudo service orchestrator start Starting orchestrator. |
Happy Orchestrating!
One of the beauties of FreeBSD is the project actually follows its own hier(7) man page, unlike. . . just about every Linux Distribution or commercial UNIX platform. The “/” prefix is for for the OS utils to get the OS booted, filesystems mounted, and get on the network. The “/usr” prefix is the rest of the OS, and the “/usr/local” prefix is the default location for ports/package managed software. Your instructions to create a “/usr/local/orchestrator” directory, then break the prefix hierarchy created by it’s own build process, knock heads with this clean separation.
I would instead recommend creating an “/opt” or “/usr/opt” prefix for manually built/installed or commercial software. (I’ll stick with “/usr/opt” for this example.)
Your orchestrator & resources binaries can go into /usr/opt/bin/. Your init script can be “/usr/opt/etc/rc.d/orchestrator” then you can tell the OS about this location by placing this line in /etc/rc.conf:
local_startup=”/usr/local/etc/rc.d /usr/opt/etc/rc.d” # startup script dirs.
You can then add the /usr/opt/bin directory to the system path, if you wish, by modifying /etc/login.conf:
default:\
:passwd_format=sha512:\
:copyright=/etc/COPYRIGHT:\
:welcome=/etc/motd:\
:setenv=MAIL=/var/mail/$,BLOCKSIZE=K:\
:path=/sbin /bin /usr/sbin /usr/bin /usr/local/sbin /usr/local/bin /usr/opt/bin ~/bin:\
(Don’t forget to run ‘cap_mkdb /etc/login.conf’ to make it official.)
Sorry, the comment editor butchered my whitespace & formatting.
Hi Glen, thanks for chiming in. I will update the tutorial based on your comments when I get a chance.