arcshell

Getting Started

The steps below are just meant to get you up and running with ArcShell as quickly as possible. Make sure you take time to watch the videos too.

Steps About
Step 1 Install ArcShell using a tar.gz file.
Step 2 Register an SSH connection.
Step 3 Configure your “arcshell.config” file.
Step 4 Update your “admins” contact group.
Step 5 Start the ArcShell service daemon.

Install ArcShell using a tar.gz file.

In this example I am installing ArcShell on a Microsoft Azure RedHat virtual machine.

A note about using “rm” and “cp” aliases - ArcShell unsets any aliases defined as “rm” or “cp”. These aliases can interfere with ArcShell’s ability to operate.

[arclogic@azure arcshell]$ uname -a
Linux azure 3.10.0-693.11.6.el7.x86_64 #1 SMP Thu Dec 28 14:23:39 EST 2017 x86_64 x86_64 x86_64 GNU/Linux
[arclogic@azure ~]$ hostname
azure

You must be using a Bash or Korn shell to install ArcShell. Make sure you verify!

[arclogic@azure arcshell]$ echo $0
-bash

I am going to install ArcShell to the ${HOME}/app/arcshell directory. Any directory with the exception of ${HOME}/arcshell is allowed. ${HOME}/arcshell is a reserved directory path and should not be used to install.

# I am in my home directory. Not the right place to install ArcShell.
[arclogic@azure ~]$ pwd
/home/arclogic
# I will create an app directory to house ArcShell.
[arclogic@azure ~]$ mkdir -p app
# cd to the app directory.
[arclogic@azure ~]$ cd app

You should have recieved your own custom download link. The link below is not functional. Replace the download link below with the link you were given.

[arclogic@azure app]$ wget -q -O "./arcshell.tar.gz" "https://www.dropbox.com/s/sdjn33jkj4jffrk1w/arcshell.tar.gz"
[arclogic@azure app]$ ls 
arcshell.tar.gz
[arclogic@azure app]$ gunzip arcshell.tar.gz
[arclogic@azure app]$ tar -xf arcshell.tar
[arclogic@azure app]$ ls
arcshell_2018.11.07.23.18  arcshell.tar
[arclogic@azure app]$ mv arcshell_2018.11.07.23.18 arcshell
[arclogic@azure app]$ cd arcshell

Run the setup program.

[arclogic@azure arcshell]$ ./arcshell_setup.sh
     _               ____  _          _ _ 
    / \   _ __ ___  / ___|| |__   ___| | |
   / _ \ | '__/ __| \___ \| '_ \ / _ \ | |
  / ___ \| | | (__   ___) | | | |  __/ | |
 /_/   \_\_|  \___| |____/|_| |_|\___|_|_|                      
                          
arclogicsoftware.com
http://bit.ly/ethan_ray_post
ethan@arclogicsoftware.com
(931) 450-8899
Copyright 2018 ArcLogic Software
All Rights Reserved
Setting up Arcshell.
ArcShell version is 2018.11.07.23.18
Processing modules.
Loading the ArcShell environment.
Securing ArcShell files and directories.
Setup complete!
[arclogic@azure arcshell]$ 

ArcShell is ready.


Registering an SSH connection.

Source in ArcShell and list the SSH connections which are already registered.

ethan@devgame:~$ . ~/.arcshell
ethan@devgame:~$ ssh_list
dev1@ubuntu16
dev@devgame
epost@ubuntu16
ethan@devgame
tst@devgame

Add a new SSH connection using ssh_add I am assigning the alias “azure” to this connection to make it easier to reference in the future.

ethan@devgame:~$ ssh_add -port 22 -alias azure "arclogic@23.96.113.25"
'arclogic@23.96.113.25' has been configured using '/media/sf_temp/arcshell/arcshell/config/ssh_connections/arclogic@23.96.113.25'.

Run ssh_refresh when you are finished adding or modifying connections.

ethan@devgame:~$ ssh_refresh
SSH connections have been refreshed.

List the connections again using the -l switch. This is called the long listing and will return the full path to the configuration file for each node.

ethan@devgame:~$ ssh_list -l
/media/sf_temp/arcshell/arcshell/config/ssh_connections/arclogic@23.96.113.25
/media/sf_temp/arcshell/arcshell/config/ssh_connections/dev1@ubuntu16
/media/sf_temp/arcshell/arcshell/config/ssh_connections/dev@devgame
/media/sf_temp/arcshell/arcshell/config/ssh_connections/epost@ubuntu16
/media/sf_temp/arcshell/arcshell/config/ssh_connections/ethan@devgame
/media/sf_temp/arcshell/arcshell/config/ssh_connections/tst@devgame

We can edit the SSH connection by editing the file.

ethan@devgame:~$ vi /media/sf_temp/arcshell/arcshell/config/ssh_connections/arclogic@23.96.113.25

You can also create a new connection by copying and renaming a file, then running ssh_refresh.

# Generated using 'ssh_add'.

# An alias makes it easy to refer to the node.
node_alias="azure"

# One or more tags. Use commas between tags.
node_tags=""

# The ssh port to connect to. Defaults to 22 if not provided.
node_port=22

# Private key file path or just the name if it is in your 'ssh_keys' folders.
node_ssh_key=""

# Use "sshpass" program if installed?
node_use_sshpass=0

# Optionally supply ths SSHPASS value to avoid having to provide it the first time.
node_SSHPASS=""

Test the connection using ssh_connect.

ethan@devgame:~$ ssh_connect azure
Setting ssh connection to 'arclogic@23.96.113.25'
The authenticity of host '23.96.113.25 (23.96.113.25)' cannot be established.
ECDSA key fingerprint is SHA256:B22zNEGPidje7d3jj3u7d7d7dj6pLM9N0bk3GahFG6o.
Are you sure you want to continue connecting (yes/no)? yes
Warning: Permanently added '23.96.113.25' (ECDSA) to the list of known hosts.
Welcome to Ubuntu 18.04.1 LTS (GNU/Linux 4.15.0-1030-azure x86_64)
...
0 packages can be updated.
0 updates are security updates.

arclogic@azure:~$ 

Configure your “arcshell.config” file.

The command below will open the global “arcshell.config” configuration file. It is located in ${arcHome}/arc/config/arcshell directory.

arclogic@azure:~$ arc_edit_config

Define values for arc_admin_emails, arc_admin_texts, and the messaging_from_address. If you are using an external SMTP mail provider you may need to make sure the from address matches the SMTP email domain.


# ------------------------------------------------------------------------------
# Messaging
# ------------------------------------------------------------------------------

# From address to use for emails. Your SMTP provider may block if this is not 
# correctly defined.
messaging_from_address="DoNotReply@acme.com"

# Message subject prefix. 
messaging_prefix="[ArcShell]"

# Default keyword to use if one is not provided when calling "send_message".
messaging_default_keyword="email"

# Note, if another program is used here contact support. Only mail and mailx.
# If you need to use another program contact support and let us know.
messaging_mail_program="mail"

Save the file when you are finished editing it. You will need to source ArcShell in again to pick up the new settings.

arclogic@azure:~$ arcHome=
arclogic@azure:~$ . ~/.arcshell

Update the ‘admins’ contact group.

ArcShell routes messages to one or more team members using “contact_groups”.

List the available contact groups. “admins” is the only delivered group.

arclogic@azure:~$ . ~/.arcshell
arclogic@azure:~$ contact_groups_list -l

Edit the global “admins” contact group configuration file.

/home/arclogic/app/arcshell/arcshell/config/contact_groups/admins
arclogic@azure:~$ vi /home/arclogic/app/arcshell/arcshell/config/contact_groups/admins

This is the contents of the file after being edited. You should provide at least one “group_emails” address and optionally at least one “group_texts” address. Save the file after you are done making your changes.

arclogic@azure:~$ cat /home/arclogic/app/arcshell/arcshell/config/contact_groups/admins

# Note, if you see [*] it means any "truthy" value will work including cron expressions.

# List of email addresses to use with the group.
# group_emails="${email},${email}"
group_emails="foo@acme.com"

# List of SMS text email addresses to use with the group.
# group_texts="${email},${email}"
group_texts="555555555@vtext.com"

# Do you want this group to be the default group? [*]
group_default_group=

# Is group enabled? [*]
group_enabled=""

# Is group disabled? [*]
group_disabled=""

# Is group on hold? [*]
group_hold=""

# Are texts disabled for the group? [*]
group_disable_texts=""

# Send pending emails if oldest item in queue is older than X seconds.
group_max_email_queue_seconds=0

# Send pending emails if queue has been idle for X seconds.
group_max_email_queue_idle_seconds=0

# Send pending emails if number of items in queue exceeds X.
group_max_email_queue_count=0

# Send pending texts if oldest item in queue is older than X seconds.
group_max_text_queue_seconds=0

# ** FUTURE ** 
# A schedule used to send status reports to the group.
# group_report_schedule=
# A schedule used to send any pending items in the queues.
# group_delivery_schedule=

Run the “contact_groups_refresh” process when you are done making changes.

arclogic@azure:~$ contact_groups_refresh
Contact groups have been refreshed.

If the server you are installed ArcShell on has the capability to send email you can test your changes by trying to send yourself an email and/or a text.

arclogic@azure:~$ echo "Hello Team" | send_message -keyword email -now
arclogic@azure:~$ echo "Hello Team" | send_message -keyword text -now

Start the ArcShell service daemon.

To begin running the scheduled jobs start the ArcShell daemon.

$ . ~/.arcshell                  
$ nohup arcshell.sh start &
[1]	25920
$ nohup: ignoring input and appending output to 'nohup.out'

Add the following to your crontab (or other scheduling tool) to keep ArcShell running between reboots.

$ which arcshell.sh
/home/ethan/arcshell/arcshell.sh
$ crontab -l
* * * * * /home/ethan/arcshell/arcshell.sh autostart 1>> "${HOME}/cron.log" 2>> "${HOME}/cron.err"

NOTE Scheduled tasks should not typically return output to standard out or error. When it happens it can be an indication of an error or possible oversight. If this goes unnoticed for too long these files can begin to chew up quite a bit of disk space. In general you want to be sure ArcShell is installed on a volume that has at least 2-3 GB of available space.

To list additional commands see help.

$ arcshell.sh -help

arcshell.sh  [-help] [-debug X] [option]

-help       Return help for this program.
-debug      Set the daemon debug level (1-3).
start       Starts the daemon. Does nothing is already started.
autostart   Starts the deamon if it has been stopped unexpectedly.
stop        Stops the daemon. This can take up to 60 seconds.
restart     Stops and starts the daemon.
status      Returns 'started', 'suspended', or 'stopped'.
kill        Kills the daemon if it is running.
suspend     Puts daemon is suspend status. Stops daemon if started.
resume      Restores the daemon to the state prior to being suspended.

Once the service is running you may want to monitor the application log file for activity. To find the location of the application log file run this.

$ log_show
The current log file is set to "/home/ethan/arcshell/log/arcshell.log"...
> -rw-r--r-- 1 ethan ethan 698314 Nov 20 13:26 /home/ethan/arcshell/log/arcshell.log
To change the file, run the following:
log_set_file "${path_to_log_file}"
Log entries are currently being written to:
> '/home/ethan/arcshell/log/arcshell.log'
To change the output targets run the 'log_set_output' command.
Run 'log_help' or 'log_help -aa' for more.

You can tail the log file in the background without needing to recall the exact location by running “log_follow”.

$ log_follow
[2]	30323
$ 1542742082 BORING [scheduler] ethan@devgame 2018-11-20 13:28:02 [01m] pid=28346;file='/media/sf_temp/arcshell/schedules/01m/collect_vmstats.sh'
1542742082 BORING [scheduler] ethan@devgame 2018-11-20 13:28:02 [01m] pid=28424;file='/media/sf_temp/arcshell/schedules/01m/monitor_cpu_usage.sh'
1542742105 INFO [27243] ethan@devgame 2018-11-20 13:28:25 [] CPU usage is 72%.

Use “log_quit” to stop following the application log file.

$ log_quit
[2]-  Killed                  tail -f "${f}"

Take a minute to check for any obvious errors in these files after the service daemon has been running for a while.

$ ll "${HOME}/cron"* "${HOME}/arcshell.err"
-rw-r--r-- 1 ethan ethan 0 Nov 20 14:32 /home/ethan/arcshell.err
-rw-rw-r-- 1 ethan ethan 0 Nov 20 10:11 /home/ethan/cron.err
-rw-rw-r-- 1 ethan ethan 0 Nov 20 10:11 /home/ethan/cron.log

NOTE In the future we will add a separate program to monitor these files automatically for you independent of the framework.