= Connectshares User Guide 
:connectshares-page:

{start-toc}

[[toc]]
[compact]
* link:#under-toc[Conventions]
* link:#_what_is_connectshares[What is Connectshares?]
* link:#_features[Features]
* link:#_getting_started[Getting Started]
* link:#_setting_up_connectshares[Setting Up Connectshares]
* link:#_connecting_to_remote_shares[Connecting to Remote Shares]
* link:#_viewing_the_connected_shares[Viewing the Connected Shares]
* link:#_disconnecting_from_remote_shares[Disconnecting from Remote Shares]
* link:#_shares_on_multiple_remote_systems[Shares on Multiple Remote Systems]
* link:#_summary_of_files[Summary of Files]
* link:#_video[Video]

{nbsp}

{nbsp}




[[under-toc]]
== Conventions
{top}
[icon="./images/icons/info.png"]
[NOTE]
This is additional information

[icon="./images/icons/tip2.png"]
[NOTE]
This is a tip

[icon="./images/icons/settings.png"]
[NOTE]
This is an example configuration or setting

{nbsp}

{nbsp}



== What is Connectshares?
{top}

It is a simple way of connecting your local antiX system to shared 
directories offered by a remote system in a local network (often 
known as a LAN).

It searches the LAN and displays information about the shares it 
finds.  You nominate the shares you want to connect to and then connect.

Your nominations are saved to a file and can (optionally) be used 
to connect to the shares automatically each time you log in to your 
antiX system.  If you prefer not to connect automatically at log in, 
connections can be made on demand, after log in, via the antiX menu.

{nbsp}

{nbsp}




== Features
{top}

* Connects to shares offered by Windows systems and Linux systems (often 
  known as Samba and NFS).
* Connections to multiple remote shares can be established simultaneously 
  in one group action.
* Automatically connects to shares that are not password protected.
* For password protected shares, the user has the option of connecting 
  automatically or manually. +
  Automatic connection is done without prompting for name and password. +
  Manual connection requires the input of name and password in order to 
  gain access to the share.
* Connecting to shares can be automated to happen at each log in.  
  Alternatively connections can be done on demand via the usual antiX 
  menu (or even a desktop shortcut).
* Connections to all share types are made without editing any files owned 
  by root.
* The root password is not required when configuring Connectshares, nor 
  when connecting and disconnecting shares
* Your normal user account is used to make the connection.
* Connections can be disabled by share type. For example, if you only 
  require to connect to Windows or Samba systems attempts to connect to 
  NFS shares can be prevented.
* Disconnecting shares may be done individually or as a group.
* All configuration and reporting of discovered shares is done via a 
  pseudo GUI.  The command line is not used.
* Works in both CLI (no X) and GUI environments.
* Does not require dedicated software e.g. user space file system app, 
  file manager or network file manager,
* Tiny amount of storage space is used by Connectshares and related files.

{nbsp}

{nbsp}




== Getting Started
{top}

Before a connection can be made, Connectshares needs to be provided with 
some information.  It needs to know which remote system to connect to and 
whether (or not) to request a name and a password for password protected 
shares.

[icon="./images/icons/info.png"]
[TIP]
Setting up to connect to remote shares is usually done once only. 

It takes two steps. When these have been done you can then choose whether 
to automatically connect to the shares at each log in.  This is a separate 
step as it is an antiX configuration rather than Connectshares one.

{nbsp}

{nbsp}




== Setting Up Connectshares
{top}

From the antiX menu select +
image:connectshares-config.png[]^Connectshares Configuration^

It is a good idea to start by selecting the "Help" button.  This will 
display a brief guide of the two steps used to set up a connection.  
It also describes how to use the options in the main configuration menu.

=== Step 1 - Discover which shares are available
From the configuration menu select +
**1. Find shares offered by a remote system**

This searches the network for file servers and the shares they are serving.
In the majority of cases servers and shares are found without a problem.  

[icon="./images/icons/tip2.png"]
[TIP]
If none are shown, check: +
1. The remote server is allowed to send out information +
2. The local system firewall is not blocking the reply being received

After a successful discovery, a summary is displayed from which you choose 
the shares to connect to your antiX system. 

[icon="./images/icons/tip2.png"]
[TIP]
To connect to a Samba server you need the following from the summary: +
1. The name or IP address of the remote system + 
2. The name of the workgroup to which shares are served + 
3. The name of each share you want to access

You enter your choices in step 2.

=== Step 2 - Save your choice of shares in a file
From the configuration menu select +
**2. Nominate shares to connect from remote system**

This opens the file ready for you to add the server and share details. 
The default configuration file is named connectshares.conf. Use this when 
connecting to shares from a single remote system.

[icon="./images/icons/tip2.png"]
[TIP]
To open connectshares.conf +
1. Use the Tab key to move the cursor into the Files panel +
2. Use the arrow keys to highlight connectshares.conf +
3. Use the spacebar key to select connectshares.conf +
4. Press the OK button

Using the guidance provided, enter the information from the discovery step.

=== Example Configuration to Connect to Samba Shares
The following adds the details of the Samba server and shares discovered 
in step 1. 

In summary it:

* Specifies the remote system to connect, 
* Activates connecting to Windows and Samba shares, 
* Connects to shares that do not require a password and also those that are password protected,
* Automatically supplies your name and password without prompting you

[icon="./images/icons/settings.png"]
[NOTE]
==== 
connectshares.conf
----
# -------------
# Remote System
# -------------

# The name or IP address of the remote system serving the share(s)
# Examples
#   REMOTE=shareserver
#   REMOTE=192.168.1.50
REMOTE=192.168.2.3


# ------------
# Samba Shares
# ------------

# Enable/disable the mounting of Samba shares from the remote system
# When disabled, all other entries in "Samba Shares" section are ignored
# Leave empty to disable mounting, add y to enable mounting
# Examples
#   SAMBA=
#   SAMBA=y
SAMBA=y


# The name of the domain in which the remote system serves Samba shares(s)
# Examples
#   WORKGROUP=company
#   WORKGROUP=workgroup
WORKGROUP=workgroup


# Samba shares on the remote system that require a user name and password
# Leave empty to disable mounting shares of this type
# Each listed share must include only the share name terminated by a comma
# Multiple shares must be specified as a comma separated list
# A space immediately before or immediately after a comma is not allowed
# Examples
#   SHARESUSER=
#   SHARESUSER=homes,
#   SHARESUSER=accounts,homes,video clips,
SHARESUSER=homes,video clips,
#
# Enable/disable automatically supplying user name and password to remote Samba server
# When disabled a request to manually input credentials is displayed
# Leave empty to disable automatic credentials mode, add y to enable automatic credentials mode
# Examples
#   CREDAUTO=
#   CREDAUTO=y
CREDAUTO=y
#
# The name and password to be supplied when automatic credentials mode is enabled
# When automatic credentials mode is disabled, these entries are ignored and may be left empty
# Examples
#   CREDNAME=popeye
#   CREDPASS=spinach
CREDNAME=olive
CREDPASS=opensessame


# Samba shares on the remote system that do not require a user name and password
# The shares must allow access to guests
# Leave empty to disable mounting shares of this type
# Each listed share must include only the share name terminated by a comma
# Multiple shares must be specified as a comma separated list 
# A space immediately before or immediately after a comma is not allowed
# Examples
#   SHARESGUEST=
#   SHARESGUEST=anyone,
#   SHARESGUEST=anyone,guest only,
SHARESGUEST=anyone,
----
====
For this example all other configuration values may safely be left empty.

After entering and saving the details, setting up is complete.  Your saved 
choices will be used when connecting to the remote system.

{nbsp}

{nbsp}




== Connecting to Remote Shares
{top}

Connecting can be done in two ways

* On-demand (you choose when to do it),
* Automatically each time you log in (even if you have set your antiX 
  system to log in at boot up without prompting for your username and password)

=== On-Demand
From the antiX menu select +
image:connectshares/connectshares.png[]^Connectshares^

=== Automatically
From the antiX menu select +
Control Center->System->Edit Fluxbox, IceWM or JWM Settings  (choose the 
one you are using)

In the startup tab, edit the following section to read
[icon="./images/icons/settings.png"]
[NOTE]
==== 
startup
----
# mount Samba and/or NFS shares
sleep 2 && connectshares &
----
====

[icon="./images/icons/info.png"]
[NOTE]
====
It might be possible for the line to read
----
connectshares &
----
This will remove a 2 second delay and so make your antiX system available 
more quickly.
====

Save the file.  The next time your system boots up or when you next log 
in the shares will be connected for you.

If you boot a laptop while you are away from your local network, Connectshares 
will still try to connect your shares.  After a brief period it will stop 
and advise you that your share server cannot be reached.  While it is trying 
to make the connection you can continue to use your system as usual.

{nbsp}

{nbsp}




== Viewing the Connected Shares
{top}

To provide easy access to the shares, a shortcut link is created in your 
home directory named either with the IP address or name of the remote system. +
image:connectshares/home-dirs.png[]

Selecting the link in your file manager or other application displays
each of the connected shares. +
image:connectshares/connected-shares.png[]

{nbsp}

{nbsp}




== Disconnecting from Remote Shares
{top}

Disconnecting can be done in two ways

* On-demand (you choose when to do it and which shares to disconnect),
* Automatically each time shut down your antiX system in the usual way. 
  All shares are disconnected.

=== On-Demand 
From the antiX menu select +
image:connectshares/disconnectshares.png[]^Disconnectshares^

[icon="./images/icons/tip2.png"]
[TIP]
To select shares to disconnect +
1. Use the arrow keys to highlight a share +
2. Use the spacebar key to select the share +
3. Press the OK button
Choose one or more shares.

=== Automatically
You don't need to setup anything.  antiX will disconnect the shares as 
part of its normal shut down routine.

{nbsp}

{nbsp}




== Shares on Multiple Remote Systems
{top}

In many small office networks and also in home networks, one or more shares 
are served from a single system. Connectshares is well suited to use in 
these circumstances using its default configuration file. 

In cases where multiple remote machines serve shares, Connectshares can 
be used by creating a separate configuration file for each remote system.

Adding an additional configuration file is a two step process +
From the antiX menu select +
image:connectshares-config.png[]^Connectshares Configuration^

=== Step 1 - Discover which shares are available
Follow the same process as described previously.

=== Step 2 - Save your choice of shares in a file
From the configuration menu select +
*3. Create a new configuration file*

This lets you copy a template configuration file and opens it ready to add 
the server and share details of the additional remote system. You may give 
the file any name.  In this example its named connectshares-2.conf.

[icon="./images/icons/tip2.png"]
[TIP]
To create and open the new configuration file +
1. Use the Tab key to move the cursor into the Files panel +
2. Use the arrow keys to highlight template.conf +
3. Use the spacebar key to select template.conf +
4. Rename the file (e.g. connectshares-2.conf) +
5. Press the OK button

Enter the configuration into connectshares-2.conf as previously described.

=== Automatically Connect at Log In
From the antiX menu select +
Control Center->System->Edit Fluxbox, IceWM or JWM Settings  (choose 
the one you are using)

In the startup tab, edit the following section to read
[icon="./images/icons/settings.png"]
[NOTE]
==== 
startup
----
# mount Samba and/or NFS shares
sleep 2 && connectshares &
sleep 2 && connectshares connectshares-2.conf &
----
====

[icon="./images/icons/info.png"]
[NOTE]
====
It might be possible to for the lines to read
----
connectshares &
connectshares connectshares-2.conf &
----
This will remove both 2 second delays and so make your antiX system 
available more quickly.
====

Save the file.  The next time your system boots up or when you next log 
in the shares from both remote systems will be connected for you.

{nbsp}

{nbsp}




== Summary of Files
{top}

All configuration files are located in /home/USERNAME/.config/connectshares/

* connectshares.conf is the default configuration file,
* template.conf is the template from which additional configurations are 
  created.

All executable files are located in /usr/local/bin/

* connectshares in GUI a environment launches a terminal for connectshares.sh
* connectshares.sh does the connection work
* connectshares-config in a GUI environment a launches a terminal for 
  connectshares-config.sh
* connectshares-config.sh does the configuration work
* disconnectshares in a GUI environment a launches a terminal for 
  disconnectshares.sh
* disconnectshares.sh does the disconnection work

[icon="./images/icons/tip2.png"]
[NOTE]
====
To display a description of an executable file +
1. Open a terminal +
2. Enter the command _filename --help_ +
For example
----
connectshares.sh --help
----
====

All menu files are located in /usr/share/applications/antix/

* connectshares.desktop 
* connectshares-config.desktop
* disconnectshares.desktop

All icon files are located in /usr/share/pixmaps/

* connectshares.png
* connectshares-config.png
* disconnectshares.png

== Video
antiX 15 - Find and Mount Network Shares by runwiththedolphin
https://www.youtube.com/watch?v=pp95SzXLp7Q
