This is an automated email from the ASF dual-hosted git repository.
shamrick pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/trafficcontrol.git
The following commit(s) were added to refs/heads/master by this push:
new 5f996a9 Traffic Portal Server Options (#6191)
5f996a9 is described below
commit 5f996a913d017c3d98f2f89ac2e7542c90fee5b9
Author: ocket8888 <[email protected]>
AuthorDate: Thu Sep 16 07:31:59 2021 -0600
Traffic Portal Server Options (#6191)
* Add the ability to traffic portal to specify a config file location with
'-c'
* Add the ability to override config file through grunt by setting
TP_SERVER_CONFIG_FILE env var
* Add the ability to send TP logs directly to stdout
* Add TP config file documentation
Also fixed some bugs, e.g. an unintentionally blockquote-d list, a
sub-list incorrectly being used as a term definition for a parent list
item that was not a term, etc.
* Update CHANGELOG
---
CHANGELOG.md | 1 +
docs/source/admin/index.rst | 2 +-
docs/source/admin/traffic_portal/index.rst | 112 ++++++++++++++++++++++
docs/source/admin/traffic_portal/installation.rst | 65 -------------
docs/source/development/traffic_portal.rst | 18 ++--
traffic_portal/Gruntfile.js | 4 +-
traffic_portal/README.md | 6 ++
traffic_portal/grunt/express.js | 18 +++-
traffic_portal/package-lock.json | 1 +
traffic_portal/server.js | 45 ++++++---
10 files changed, 175 insertions(+), 97 deletions(-)
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 3cdeb0c..69b2b51 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -7,6 +7,7 @@ The format is based on [Keep a
Changelog](http://keepachangelog.com/en/1.0.0/).
### Added
- [#5674](https://github.com/apache/trafficcontrol/issues/5674) Added new
query parameters `cdn` and `maxRevalDurationDays` to the `GET /api/x/jobs`
Traffic Ops API to filter by CDN name and within the start_time window defined
by the `maxRevalDurationDays` GLOBAL profile parameter, respectively.
- [#6034](https://github.com/apache/trafficcontrol/issues/6034) Added new
query parameter `cdn` to the `GET /api/x/deliveryserviceserver` Traffic Ops API
to filter by CDN name
+- A new Traffic Portal server command-line option `-c` to specify a
configuration file, and the ability to set `log: null` to log to stdout
(consult documentation for details).
### Fixed
- Fixed Traffic Router crs/stats to prevent overflow and to correctly record
the time used in averages.
diff --git a/docs/source/admin/index.rst b/docs/source/admin/index.rst
index 3c4087d..dbf6396 100644
--- a/docs/source/admin/index.rst
+++ b/docs/source/admin/index.rst
@@ -44,7 +44,7 @@ Once everything is installed, you will need to configure the
servers to talk to
traffic_ops.rst
environment_creation.rst
- traffic_portal/*
+ traffic_portal/index.rst
traffic_monitor.rst
traffic_router.rst
traffic_router/migrationto2-3.rst
diff --git a/docs/source/admin/traffic_portal/index.rst
b/docs/source/admin/traffic_portal/index.rst
new file mode 100644
index 0000000..4880326
--- /dev/null
+++ b/docs/source/admin/traffic_portal/index.rst
@@ -0,0 +1,112 @@
+..
+..
+.. Licensed under the Apache License, Version 2.0 (the "License");
+.. you may not use this file except in compliance with the License.
+.. You may obtain a copy of the License at
+..
+.. http://www.apache.org/licenses/LICENSE-2.0
+..
+.. Unless required by applicable law or agreed to in writing, software
+.. distributed under the License is distributed on an "AS IS" BASIS,
+.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+.. See the License for the specific language governing permissions and
+.. limitations under the License.
+..
+
+**************
+Traffic Portal
+**************
+Traffic Portal is only supported on CentOS Linux distributions version 7.x and
8.x. It runs on `NodeJS <https://nodejs.org/>`_ and requires version 12 or
higher.
+
+Installing
+==========
+#. Build the Traffic Portal RPM using the instructions in :ref:`dev-building`.
+#. Copy the Traffic Portal RPM to your server
+#. Install NodeJS. This can be done by building it from source, installing
with :manpage:`yum(8)` if it happens to be in your available repositories (at
version 12+), or using the NodeSource setup script.
+
+ .. code-block:: bash
+ :caption: Installing NodeJS using the NodeSource Setup Script
+
+ curl --silent --location https://rpm.nodesource.com/setup_12.x
| sudo bash -
+
+#. Install the Traffic Portal RPM with :manpage:`yum(8)` or :manpage:`rpm(8)`
e.g. by running ``yum install path/to/traffic_portal.rpm`` as the root user or
with :manpage:`sudo(8)`.
+
+
+Configuring
+===========
+Traffic Portal is primarily configured through three different files that
affect different parts of its behavior. Those files are detailed in this
section.
+
+``/etc/traffic_portal/conf/config.js``
+--------------------------------------
+This file controls the behavior of the Traffic Portal server. It is a
JavaScript source file which **MUST** set ``module.exports`` to the value of a
configuration object. Configuration objects have the following allowed
properties.
+
+.. tip:: If Traffic Portal is being upgraded, reconcile ``config.js`` with
``config.js.rpmnew`` and then delete ``config.js.rpmnew``.
+
+:api: The properties of this object control Traffic Portal's interactions with
the :ref:`to-api`.
+
+ :base_url: The **full** URL that points to the root of the
:ref:`to-api`, e.g. ``https://trafficops.infra.ciab.test:443/api/`` **not**
``https://trafficops.infra.ciab.test:443`` or
``https://trafficops.infra.ciab.test:443/api`` (trailing ``/`` required).
+
+:files: The properties of this object describe system paths important to
Traffic Portal (other than SSL-related files, which are kept in the ``ssl``
object).
+
+ :static: The directory where the built Traffic Portal front-end files
are kept. In most cases, changing this from the default is
unnecessary/discouraged.
+
+:log: The properties of this object describe the logging behavior of Traffic
Portal. If this property is missing, or is ``null`` (or other "falsey" values),
then logging is done simply on STDOUT.
+
+ :stream: Defines a file location for Traffic Portal's access logs. If
this property is missing, or is ``null`` (or other "falsey" values), then logs
will go to STDOUT instead.
+
+:port: A port number that sets the port on which Traffic Portal
will listen for insecure (HTTP) connections. If ``useSSL`` is ``false``,
requests made to this port will be redirected to use HTTPS on the ``sslPort``
instead of just serving content insecurely.
+:reject_unauthorized: A boolean that defines whether or not Traffic Portal
will reject SSL certificates that fail to validate as trusted.
+
+ .. caution:: Setting this to ``false`` exposes Traffic Portal to
security vulnerabilities such as man-in-the-middle attacks, and should *never*
be done in a production setting.
+
+:ssl: This object has properties that set the locations of SSL keys and
certificates. Has no effect if ``useSSL`` is ``false``.
+
+ :key: The file location of the SSL certificate private key.
+ :cert: The file location of the x509 SSL certificate that Traffic
Portal will use.
+ :ca: The file locations of the full certificate chain for the
certificate authority that signed the SSL key (in order).
+
+:sslPort: A port number that sets the port on which Traffic Portal will listen
for secure (HTTPS) connections. Has no effect if ``useSSL`` is ``false``.
+:useSSL: A boolean that defines whether or not the Traffic Portal instance
will offer secure (HTTPS) connections.
+
+ .. caution:: Setting this to ``false`` can expose sensitive data such
as authentication credentials. Do not *ever* do that in a production setting.
+
+:timeout: This property defines the maximum time for which Traffic Portal will
process requests before sending a timeout response. It can be either a number
of milliseconds, or a duration string accepted by `the ms library
<https://www.npmjs.com/package/ms#readme>`_.
+
+ .. warning:: Slow requests will continue to use CPU and memory, even
though a response has already been sent to the client.
+
+``/opt/traffic_portal/public/traffic_portal_properties.json``
+-------------------------------------------------------------
+- update :file:`/opt/traffic_portal/public/traffic_portal_properties.json` (if
Traffic Portal is being upgraded, reconcile
:file:`traffic_portal_properties.json` with
:file:`traffic_portal_properties.json.rpmnew` and then delete
:file:`traffic_portal_properties.json.rpmnew`)
+
+``/opt/traffic_portal/public/resources/assets/css/custom.css``
+--------------------------------------------------------------
+This :abbr:`CSS (Cascading Style Sheets)` file is provided for users to insert
CSS to override the default styling of Traffic Portal.
+
+Configuring OAuth Through Traffic Portal
+========================================
+See :ref:`oauth_login`.
+
+
+Starting Traffic Portal
+=======================
+The Traffic Portal RPM comes with a :manpage:`systemd(1)` unit file, so under
normal circumstances Traffic Portal may be started with :manpage:`systemctl(1)`.
+
+.. code-block:: bash
+ :caption: Starting Traffic Portal
+
+ systemctl start traffic_portal
+
+Stopping Traffic Portal
+=======================
+The Traffic Portal RPM comes with a :manpage:`systemd(1)` unit file, so under
normal circumstances Traffic Portal may be stopped with :manpage:`systemctl(1)`.
+
+.. code-block:: bash
+ :caption: Stopping Traffic Portal
+
+ systemctl stop traffic_portal
+
+Using Traffic Portal
+====================
+.. toctree::
+
+ ./usingtrafficportal.rst
diff --git a/docs/source/admin/traffic_portal/installation.rst
b/docs/source/admin/traffic_portal/installation.rst
deleted file mode 100644
index 077dd4e..0000000
--- a/docs/source/admin/traffic_portal/installation.rst
+++ /dev/null
@@ -1,65 +0,0 @@
-..
-..
-.. Licensed under the Apache License, Version 2.0 (the "License");
-.. you may not use this file except in compliance with the License.
-.. You may obtain a copy of the License at
-..
-.. http://www.apache.org/licenses/LICENSE-2.0
-..
-.. Unless required by applicable law or agreed to in writing, software
-.. distributed under the License is distributed on an "AS IS" BASIS,
-.. WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-.. See the License for the specific language governing permissions and
-.. limitations under the License.
-..
-
-*****************************
-Traffic Portal Administration
-*****************************
-Traffic Portal is only supported on CentOS Linux distributions version 7.x and
8.x. It runs on `NodeJS <https://nodejs.org/>`_ and requires version 12 or
higher.
-
-
-Installing Traffic Portal
-=========================
-
-#. Download the Traffic Portal RPM from `Apache Jenkins
<https://builds.apache.org/job/trafficcontrol-master-build/>`_ or build the
Traffic Portal RPM from source using the instructions in :ref:`dev-building`.
-#. Copy the Traffic Portal RPM to your server
-#. Install NodeJS. This can be done by building it from source, installing
with :manpage:`yum(8)` if it happens to be in your available repositories (at
version 12+), or using the NodeSource setup script.
-
- .. code-block:: bash
- :caption: Installing NodeJS using the NodeSource Setup Script
-
- curl --silent --location https://rpm.nodesource.com/setup_12.x
| sudo bash -
-
-#. Install the Traffic Portal RPM with :manpage:`yum(8)` or :manpage:`rpm(8)`
e.g. by running ``yum install path/to/traffic_portal.rpm`` as the root user or
with :manpage:`sudo(8)`.
-
-
-Configuring Traffic Portal
-==========================
-- update :file:`/etc/traffic_portal/conf/config.js` (if Traffic Portal is
being upgraded, reconcile :file:`config.js` with :file:`config.js.rpmnew` and
then delete :file:`config.js.rpmnew`)
-- update :file:`/opt/traffic_portal/public/traffic_portal_properties.json` (if
Traffic Portal is being upgraded, reconcile
:file:`traffic_portal_properties.json` with
:file:`traffic_portal_properties.json.rpmnew` and then delete
:file:`traffic_portal_properties.json.rpmnew`)
-- Optional: update
:file:`/opt/traffic_portal/public/resources/assets/css/custom.css` to customize
Traffic Portal styling.
-
-
-Configuring OAuth Through Traffic Portal
-========================================
-See :ref:`oauth_login`.
-
-
-Starting Traffic Portal
-=======================
-The Traffic Portal RPM comes with a :manpage:`systemd(1)` unit file, so under
normal circumstances Traffic Portal may be started with :manpage:`systemctl(1)`.
-
-.. code-block:: bash
- :caption: Starting Traffic Portal
-
- systemctl start traffic_portal
-
-Stopping Traffic Portal
-=======================
-The Traffic Portal RPM comes with a :manpage:`systemd(1)` unit file, so under
normal circumstances Traffic Portal may be stopped with :manpage:`systemctl(1)`.
-
-.. code-block:: bash
- :caption: Stopping Traffic Portal
-
- systemctl stop traffic_portal
diff --git a/docs/source/development/traffic_portal.rst
b/docs/source/development/traffic_portal.rst
index fd9fc0b..c36b337 100644
--- a/docs/source/development/traffic_portal.rst
+++ b/docs/source/development/traffic_portal.rst
@@ -29,11 +29,11 @@ Software Requirements
=====================
To work on Traffic Portal you need a \*nix (MacOS and Linux are most commonly
used) environment that has the following installed:
- * `Ruby Devel 2.0.x or above
<https://www.rpmfind.net/linux/rpm2html/search.php?query=ruby-devel>`_
- * `Compass 1.0.x or above <http://compass-style.org/>`_
- * `Node.js 12.0.x or above <https://nodejs.org/en/>`_
- * `Grunt CLI 1.2.0 or above <https://github.com/gruntjs/grunt-cli>`_
- * Access to a working instance of Traffic Ops
+* `Ruby Devel 2.0.x or above
<https://www.rpmfind.net/linux/rpm2html/search.php?query=ruby-devel>`_
+* `Compass 1.0.x or above <http://compass-style.org/>`_
+* `Node.js 12.0.x or above <https://nodejs.org/en/>`_
+* `Grunt CLI 1.2.0 or above <https://github.com/gruntjs/grunt-cli>`_
+* Access to a working instance of Traffic Ops
.. _dev-tp-global-npm:
@@ -101,10 +101,10 @@ Installing The Traffic Portal Developer Environment
#. Run ``npm install`` to install application dependencies into
``traffic_portal/node_modules``. Only needs to be done the first time unless
``traffic_portal/package.json`` changes.
#. Make sure that compass is installed and functioning correctly by running
``compass version``. If compass is not available, then it can be installed
following the instructions under :ref:`dev-tp-compass`.
-#. Modify ``traffic_portal/conf/configDev.js``:
+#. Modify :atc-file:`traffic_portal/conf/configDev.js`:
+
#. Valid SSL certificates and keys are needed for Traffic Portal to
run. Generate these (e.g. using `this SuperUser answer
<https://superuser.com/questions/226192/avoid-password-prompt-for-keys-and-prompts-for-dn-information#answer-226229>`_)
and update ``ssl``.
#. Modify ``api.base_url`` to point to your Traffic Ops API endpoint.
-#. Run ``grunt`` to package the application into ``traffic_portal/app/dist``,
start a local HTTPS server (Express), and start a file watcher.
-#. Navigate to http(s)://localhost:[port|sslPort defined in
``traffic_portal/conf/configDev.js``]
-.. note:: The Traffic Portal consumes the Traffic Ops API. Modify
traffic_portal/conf/configDev.js to specify the location of Traffic Ops.
+#. Run ``grunt`` to package the application into ``traffic_portal/app/dist``,
start a local HTTPS server (Express), and start a file watcher. To use a custom
configuration file (not just :atc-file:`traffic_portal/conf/config.js` or
:atc-file:`traffic_portal/conf/configDev.js`), set the `TP_SERVER_CONFIG_FILE`
environment variable to the location of the desired file.
+#. Navigate to http(s)://localhost:[port|sslPort defined in the configuration
file used (default: :atc-file:`traffic_portal/conf/configDev.js`)]
diff --git a/traffic_portal/Gruntfile.js b/traffic_portal/Gruntfile.js
index 13c8fe1..6e86c9d 100644
--- a/traffic_portal/Gruntfile.js
+++ b/traffic_portal/Gruntfile.js
@@ -6,9 +6,9 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
diff --git a/traffic_portal/README.md b/traffic_portal/README.md
index 88e18b8..850a990 100644
--- a/traffic_portal/README.md
+++ b/traffic_portal/README.md
@@ -22,3 +22,9 @@
An AngularJS client served from a lightweight Node.js web server. Traffic
Portal was designed to consume the Traffic Ops API.
Installation / configuration instructions may be found in [the `build/`
directory](./build/)
+
+## Server Options
+`Usage: node /path/to/server.js [-c CONFIG]`
+
+`-c CONFIG`
+ Specify a configuration file to use at path `CONFIG`, rather than just one
of `conf/config.js`, `conf/configDev.js`, or the RPM install location
(`/etc/traffic_portal/conf/config.js`)
diff --git a/traffic_portal/grunt/express.js b/traffic_portal/grunt/express.js
index 97c3bda..6fc81f7 100644
--- a/traffic_portal/grunt/express.js
+++ b/traffic_portal/grunt/express.js
@@ -6,9 +6,9 @@
* to you under the Apache License, Version 2.0 (the
* "License"); you may not use this file except in compliance
* with the License. You may obtain a copy of the License at
- *
+ *
* http://www.apache.org/licenses/LICENSE-2.0
- *
+ *
* Unless required by applicable law or agreed to in writing,
* software distributed under the License is distributed on an
* "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
@@ -17,11 +17,19 @@
* under the License.
*/
-module.exports = {
+const process = require("process");
+
+const defaultTask = {
dev: {
options: {
- script: './server.js',
- node_env: 'dev'
+ script: "./server.js",
+ node_env: "dev"
}
}
};
+
+if (Object.prototype.hasOwnProperty.call(process.env,
"TP_SERVER_CONFIG_FILE")) {
+ defaultTask.dev.options.args = ["-c", process.env.TP_SERVER_CONFIG_FILE];
+}
+
+module.exports = defaultTask;
diff --git a/traffic_portal/package-lock.json b/traffic_portal/package-lock.json
index 064c4a9..62dfbd5 100644
--- a/traffic_portal/package-lock.json
+++ b/traffic_portal/package-lock.json
@@ -5,6 +5,7 @@
"requires": true,
"packages": {
"": {
+ "name": "traffic_portal",
"version": "6.0.0",
"dependencies": {
"@uirouter/angularjs": "0.4.2",
diff --git a/traffic_portal/server.js b/traffic_portal/server.js
index 245d096..d6f12f7 100644
--- a/traffic_portal/server.js
+++ b/traffic_portal/server.js
@@ -28,19 +28,29 @@ var constants = require('constants'),
var config;
-try {
- config = require('/etc/traffic_portal/conf/config');
-}
-catch(e) {
- let file = "./conf/config";
- if((process.env.NODE_ENV || "prod") === "dev")
- file = './conf/configDev';
- config = require(file);
+// forward-compatible in case this script becomes executable with a node
+// shebang.
+if (process.argv.length === 3 || process.argv.length === 4 &&
process.argv.slice(-2)[0] === "-c") {
+ config = require(process.argv.slice(-1)[0]);
+} else {
+ try {
+ config = require('/etc/traffic_portal/conf/config');
+ }
+ catch(e) {
+ let file = "./conf/config";
+ if((process.env.NODE_ENV || "prod") === "dev")
+ file = './conf/configDev';
+ config = require(file);
+ }
}
-var logStream = fs.createWriteStream(config.log.stream, { flags: 'a' }),
- useSSL = config.useSSL;
-
+const useSSL = config.useSSL;
+let logStream;
+if (!Object.prototype.hasOwnProperty.call(config, "log") || !config.log ||
!Object.prototype.hasOwnProperty.call(config.log, "stream") ||
!config.log.stream) {
+ logStream = null;
+} else {
+ logStream = fs.createWriteStream(config.log.stream, { flags: 'a' })
+}
// Disable for self-signed certs in dev/test
process.env.NODE_TLS_REJECT_UNAUTHORIZED = config.reject_unauthorized;
@@ -84,10 +94,15 @@ app.use(modRewrite([
]));
app.use(express.static(config.files.static));
-app.use(morgan('combined', {
- stream: logStream,
- skip: function (req, res) { return res.statusCode < 400 }
-}));
+
+let morganOpts = {
+ skip: (_, res) => res.statusCode < 400
+};
+if (logStream !== null) {
+ morganOpts.stream = logStream;
+}
+
+app.use(morgan('combined', morganOpts));
app.use(timeout(config.timeout));
if (app.get('env') === 'dev') {
