Skip to content

Commit 659f5e6

Browse files
BrianSiposBrianSipos
authored
DDR updates (#2)
Updates to add references and contact info. Moving CLI troubleshooting to product guide.
1 parent 763a091 commit 659f5e6

2 files changed

Lines changed: 159 additions & 77 deletions

File tree

‎product-guide/manual.adoc‎

Lines changed: 133 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -105,6 +105,18 @@ The network protocol used for inter-container communication and for BP convergen
105105
|MGSS Implementation and Maintenance Task Requirements[[mimtar,MIMTaR]]
106106
|DOC-001819 ref F
107107

108+
|Common Access Manager (CAM) Product Guide (PG)[[cam-pg,CAM Product Guide]]
109+
|DOC-005065
110+
111+
|ANMS Architecture Description Document[[anms-add,ANMS ADD]]
112+
|DOC-005089
113+
114+
|ANMS Software Design Document[[anms-sdd,ANMS SDD]]
115+
|DOC-005445
116+
117+
|ANMS Software Interface Specification[[anms-sis,ANMS SIS]]
118+
|DOC-005446
119+
108120
|ANMS User Guide[[anms-user-guide,ANMS User Guide]]
109121
|DOC-005443
110122

@@ -125,6 +137,12 @@ The network protocol used for inter-container communication and for BP convergen
125137
|Using SELinux[[rhel8-selinux]]
126138
|https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/8/pdf/using_selinux/red_hat_enterprise_linux-8-using_selinux-en-us.pdf[rhel8-selinux]
127139

140+
|ANMS Source[[anms-source]]
141+
|https://github.com/NASA-AMMOS/anms[anms-source]
142+
143+
|ANMS Guide Document Source[[anms-docs]]
144+
|https://github.com/NASA-AMMOS/anms-docs[anms-docs]
145+
128146
|===
129147

130148

@@ -183,6 +201,11 @@ The total amount of storage needed depends on the mission use of reports, specif
183201
|7
184202
|===
185203

204+
The ANMS is designed to operate on a network where the MGSS Common Access Manager (CAM) is used to manage user accounts and a CAM Gateway is used as a reverse proxy within the ANMS installation to enforce user login sessions and access permissions.
205+
The ANMS has been exercised with CAM v5.1.0 in a test environment outside of the MGSS environment.
206+
To deploy the ANMS in an environment without a CAM instance available (or without using it) the ANMS can be built with a CAM Gateway emulator as described in <<sec-deployment-camemu>>.
207+
In any case, deployment and configuration of CAM itself is outside the scope of this document and is described in detail in the <<cam-pg>>.
208+
186209
[#sec-deployment-camemu]
187210
==== Using a CAM Gateway Emulator
188211

@@ -515,6 +538,7 @@ sudo semanage dontaudit off
515538
----
516539

517540

541+
[#sec-checkout]
518542
=== Checkout Procedures
519543

520544
Each of the following checkout procedures makes progressively more detailed and more normal-operations-like tests of the external interfaces with the ANMS.
@@ -623,16 +647,120 @@ PORT STATE SERVICE
623647
docker exec ion-manager ion_ping_peers 1 2 3
624648
----
625649

626-
== Troubleshooting
650+
== Product Support
627651

628-
=== Puppet
652+
There are two levels of support for the ANMS: troubleshooting by the administrator or user attempting to install or operate the ANMS, which is detailed in <<sec-troubleshooting>>, and upstream support via the ANMS public GitHub project, accessible as described in <<sec-contact>>.
653+
Attempts to troubleshoot should be made before submitting issue tickets to the upstream project.
629654

630-
[qanda]
631-
Errors related to the SELinux modules for the ANMS containers during installation of the ANMS on the local host, as discussed in <<sec-proc-install>>::
632-
Add the following line to the Puppet common.yaml file, typically found at `+puppet/data/common.yaml+`.
655+
[#sec-troubleshooting]
656+
=== Troubleshooting
657+
658+
==== Installation
659+
660+
This section covers issues that can occur during installation (see <<sec-proc-install>>) of the ANMS.
661+
662+
===== SELinux Blocked Behavior
663+
664+
If there are errors related to the SELinux modules for the ANMS containers during installation of the ANMS on the local host, as discussed in <<sec-proc-install>>,
665+
add the following line to the Puppet `common.yaml` file, typically found at `puppet/data/common.yaml`, and redeploy.
633666
----
634667
selinux::mode: permissive
635668
----
669+
This will result in the host being in permissive mode which allows activity not defined in SELinux modules but records those events to the system audit log.
670+
See <<sec-proc-mon-selinux>> for details on observing the audit log events.
671+
672+
CAUTION: The SELinux permissive mode is for troubleshooting only and must not be present in a production installation.
673+
674+
675+
==== Operations
676+
677+
This section covers issues that can occur after successful installation (see <<sec-proc-install>>) and checkout (see <<sec-checkout>>) of the ANMS.
678+
679+
===== Grafana Containers
680+
681+
If the Grafana panels in the `Monitor` tab displays `Connection was reset` errors, the Grafana container may not have started successfully.
682+
683+
Restart the container with `docker-compose up grafana` (run from within the `anms/` folder).
684+
685+
If restarting the container does not resolve the problem, and the Grafana startup
686+
contains errors related to only having read-only access to the database, permissions on
687+
various files in the source code will need to be updated for Grafana to run.
688+
689+
For both the `docker_data/grafana_vol/` folder and the `docker_data/grafana_vol/grafana.db`
690+
file, change the group to `docker` and the permissions to `777`:
691+
692+
```
693+
$ sudo chgrp docker docker_data/grafana__vol
694+
$ sudo chgrp docker docker_data/grafana_vol/grafana.db
695+
$ sudo chmod 777 docker_data/grafana_vol
696+
$ sudo chmod 777 docker_data/grafana_vol/grafana.db
697+
```
698+
699+
After changing these permissions, run `docker-compose up grafana` again, and the Grafana
700+
container should start sucessfully.
701+
702+
===== Agent Registration Issues on ANMS Startup
703+
704+
If an Agent is not present in the `Agents` tab on start up, it is likely due to an error in one of the ION containers and their connection to the underlying database.
705+
706+
To resolve the issue, restart the ION containers using `docker-compose restart n1 n2`.
707+
708+
===== New Agent Registration Issues
709+
710+
If registering a new Agent does not result in an update to the displayed Agents in the ANMS Agent tab, check that it has been registered to the Manager via the nm-manager CLI.
711+
The nm-manager CLI is accessible from a terminal, and this check can be done using a command such as:
712+
```
713+
docker exec -it ion-manager journalctl -f --unit ion-nm-mgr
714+
```
715+
716+
If the results confirm that the Agent is registered but it still does not show on the Agents tab of the ANMS, there may be an
717+
issue with connection between the Manager and ANMS database.
718+
719+
This can be manually resolved by adding the Agent via the adminer DB tool that is deployed as part of the docker-compose tool at http://localhost/.
720+
The connection information is described in <<sec-amp-database-querying>>.
721+
722+
723+
[#sec-amp-database-querying]
724+
===== AMP Database Querying
725+
726+
To see what is present in the underlying AMP database, use the adminer access point.
727+
728+
With ANMS running, go to `localhost:8080` and log in to the database with:
729+
- System: `PostgreSQL`
730+
- Server: `postgres`
731+
- Username: `root`
732+
- Password: `root`
733+
- Database `amp_core`
734+
735+
736+
===== ANMS-UI is not visible at hostname:9030
737+
738+
This error may indicate that the anms-ui docker is experiencing issues receiving HTTP requests.
739+
This is most likely related to the `host` or `bind address` specified in `anms-ui/server/shared/config.py`,
740+
or an environment variable that overrides this.
741+
742+
===== ANMS-UI is not visible at hostname
743+
744+
If http://hostname:9030 (replace hostname with the server's hostname) displays the ANMS UI, but
745+
http://hostname does not render the same page, this indicates an issue with NGinx.
746+
747+
Check the status of NGix in the docker-compose services list. It may be necessary to restart nginx via
748+
`docker-compose -f docker-compose.yml restart nginx`.
749+
750+
If this restart does not resolve the issue, check `nginx.conf` in the root of the ammos-anms project.
751+
Ensure that `anms-ui` or `localhost` are set to port `80` and the hostname is correct.
752+
753+
754+
[#sec-contact]
755+
=== Contacting or Contributing
756+
757+
The ANMS is hosted on a GitHub repository <<anms-source>> with submodule references to several other repositories.
758+
There is a https://github.com/NASA-AMMOS/anms/blob/main/CONTRIBUTING.md[`CONTRIBUTING.md`] document in the ANMS repository which describes detailed procedures for submitting tickets to identify defects and suggest enhancements.
759+
760+
Separate from the source for the ANMS proper, the ANMS Product Guide and User Guide are hosted on a GitHub repository <<anms-docs>>, with its own https://github.com/NASA-AMMOS/anms-docs/blob/main/CONTRIBUTING.md[`CONTRIBUTING.md`] document for submitting tickets about either the Product Guide or User Guide.
761+
762+
While the GitHub repositories are the primary means by which users should submit detailed tickets, other inquiries can be made directly via email to the the support address mailto:dtnma-support@jhuapl.edu[,ANMS Support].
763+
636764

637765
[index]
638766
== Index

‎user-guide/manual.adoc‎

Lines changed: 26 additions & 72 deletions
Original file line numberDiff line numberDiff line change
@@ -134,6 +134,12 @@ Selecting an item from a drop-down list of available options.
134134
|Grafana Panels Documentation[[grafana-panels]]
135135
|https://grafana.com/docs/grafana/latest/panels-visualizations/[grafana-panels]
136136

137+
|ANMS Source[[anms-source]]
138+
|https://github.com/NASA-AMMOS/anms[anms-source]
139+
140+
|ANMS Guide Document Source[[anms-docs]]
141+
|https://github.com/NASA-AMMOS/anms-docs[anms-docs]
142+
137143
|===
138144

139145

@@ -1015,90 +1021,38 @@ TODO: add a reference to section for issuing commands to the agent.
10151021

10161022

10171023

1024+
== Product Support
10181025

1019-
== Troubleshooting
1020-
1021-
The following sections provide troubleshooting guidance for the ANMS.
1022-
1023-
1024-
=== Grafana Containers
1025-
1026-
If the Grafana panels in the `Monitor` tab displays `Connection was reset` errors, the Grafana container may not have started successfully.
1027-
1028-
Restart the container with `docker-compose up grafana` (run from within the `anms/` folder).
1029-
1030-
If restarting the container does not resolve the problem, and the Grafana startup
1031-
contains errors related to only having read-only access to the database, permissions on
1032-
various files in the source code will need to be updated for Grafana to run.
1033-
1034-
For both the `docker_data/grafana_vol/` folder and the `docker_data/grafana_vol/grafana.db`
1035-
file, change the group to `docker` and the permissions to `777`:
1036-
1037-
```
1038-
$ sudo chgrp docker docker_data/grafana__vol
1039-
$ sudo chgrp docker docker_data/grafana_vol/grafana.db
1040-
$ sudo chmod 777 docker_data/grafana_vol
1041-
$ sudo chmod 777 docker_data/grafana_vol/grafana.db
1042-
```
1043-
1044-
After changing these permissions, run `docker-compose up grafana` again, and the Grafana
1045-
container should start sucessfully.
1046-
1047-
=== Registering an Agent
1048-
1049-
==== Agent Registration Issues on Startup
1050-
1051-
If an Agent is not present in the `Agents` tab on start up, it is likely due to
1052-
an error in one of the ION containers and their connection to the underlying database.
1053-
1054-
To resolve the issue, restart the ION containers using `docker-compose restart n1 n2`.
1055-
1056-
==== New Agent Registration Issues
1057-
1058-
If registering a new Agent does not result in an update to the displayed Agents in the ANMS Agent tab,
1059-
check that it has been registered to the ion-manager via the nm-manager CLI. The nm-manager CLI is accessible from a terminal,
1060-
and this check can be done using a command such as:
1061-
1062-
`docker exec -it ion-manager journalctl -f --unit ion-nm-mgr`
1063-
1064-
If the results confirm that the Agent is registered but it still does not show on the Agents tab of the ANMS, there may be an
1065-
issue with connection between the Manager and ANMS database.
1066-
1067-
This can be manually resolved by adding the Agent via the adminer DB tool that is deployed as part of the docker-compose tool at http://localhost/.
1068-
The connection information is described in <<sec-amp-database-querying>>.
1069-
1026+
There are two levels of support for the ANMS: troubleshooting by the administrator or user attempting to operate the ANMS, which is detailed in <<sec-troubleshooting>>, and upstream support via the ANMS public GitHub project, accessible as described in <<sec-contact>>.
1027+
Attempts to troubleshoot should be made before submitting issue tickets to the upstream project.
10701028

1071-
[#sec-amp-database-querying]
1072-
=== AMP Database Querying
1029+
[#sec-troubleshooting]
1030+
=== Troubleshooting
10731031

1074-
To see what is present in the underlying AMP database, use the adminer access point.
1032+
The following situations provide troubleshooting guidance for the ANMS from the perspective of a normal or administrative user, typically operating the ANMS via a web browser.
1033+
Each situation consists of an observed state followed by a recommended troubleshooting activity.
10751034

1076-
With ANMS running, go to `localhost:8080` and log in to the database with:
1077-
- System: `PostgreSQL`
1078-
- Server: `postgres`
1079-
- Username: `root`
1080-
- Password: `root`
1081-
- Database `amp_core`
10821035

1036+
[qanda]
1037+
The Grafana panels in the `Monitor` tab displays `Connection was reset` errors::
1038+
The Grafana container may not have started successfully. Contact a system administrator to restart the component.
10831039

1084-
=== ANMS UI Visibility
1040+
An Agent is not present in the `Agents` tab on start up::
1041+
This is likely due to an error in one of the ION containers and their connection to the underlying database. Contact a system administrator to restart the component.
10851042

1086-
==== ANMS-UI is not visible at hostname:9030
1043+
Registering a new Agent does not result in an update to the displayed Agents in the ANMS Agent tab::
1044+
Contact a system administrator to verify that the Agent has been registered to the Manager via CLI tools.
10871045

1088-
This error may indicate that the anms-ui docker is experiencing issues receiving HTTP requests.
1089-
This is most likely related to the `host` or `bind address` specified in `anms-ui/server/shared/config.py`,
1090-
or an environment variable that overrides this.
10911046

1092-
==== ANMS-UI is not visible at hostname
1047+
[#sec-contact]
1048+
=== Contacting or Contributing
10931049

1094-
If http://hostname:9030 (replace hostname with the server's hostname) displays the ANMS UI, but
1095-
http://hostname does not render the same page, this indicates an issue with NGinx.
1050+
The ANMS is hosted on a GitHub repository <<anms-source>> with submodule references to several other repositories.
1051+
There is a https://github.com/NASA-AMMOS/anms/blob/main/CONTRIBUTING.md[`CONTRIBUTING.md`] document in the ANMS repository which describes detailed procedures for submitting tickets to identify defects and suggest enhancements.
10961052

1097-
Check the status of NGix in the docker-compose services list. It may be necessary to restart nginx via
1098-
`docker-compose -f docker-compose.yml restart nginx`.
1053+
Separate from the source for the ANMS proper, the ANMS Product Guide and User Guide are hosted on a GitHub repository <<anms-docs>>, with its own https://github.com/NASA-AMMOS/anms-docs/blob/main/CONTRIBUTING.md[`CONTRIBUTING.md`] document for submitting tickets about either the Product Guide or User Guide.
10991054

1100-
If this restart does not resolve the issue, check `nginx.conf` in the root of the ammos-anms project.
1101-
Ensure that `anms-ui` or `localhost` are set to port `80` and the hostname is correct.
1055+
While the GitHub repositories are the primary means by which users should submit detailed tickets, other inquiries can be made directly via email to the the support address mailto:dtnma-support@jhuapl.edu[,ANMS Support].
11021056

11031057

11041058
[index]

0 commit comments

Comments
 (0)