> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zylon.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Samba File System

### 1. Gather Your Samba Server Information

To integrate Zylon with your on-premises Samba file server, you need the server’s connection details (host, port, share name) and valid credentials. This guide explains how to configure Zylon to use Samba for file system integration within your local networ. You’ll need:

* **Host or IP address** of the Samba server (e.g. `files.example.com` or `192.168.1.50`).
* **Port** on which SMB is listening (default is `445`; if you run on a non-standard port, note it).
* **Share (root) name** (e.g. `zylon-samba`).
* **Credentials** (username & password) that have **read** access to that share.
* **SMB protocol version support**:
  * We currently support **SMB2 and above**.
  * If you require **SMB1**, please contact the Zylon team for assistance.

To verify connectivity:

1. **Linux** (using `smbclient`):

```bash theme={null}
smbclient -L //files.example.com -U yourUser%yourPass
```

You should see a listing of shares, including `zylon-samba`.

2. **macOS** (Finder):

* In Finder, press ⌘K → connect to `smb://files.example.com/zylon-samba`.
* Enter your credentials when prompted, and verify you can browse files.

3. Windows

* **File Explorer (Graphical)**:
  1. Open **File Explorer** (Win + E).
  2. In the left sidebar, right-click **This PC** and choose **Map network drive…**.
  3. In the **Drive** dropdown, select an available drive letter (e.g., `Z:`).
  4. In the **Folder** field, enter:
     (or if using a non-standard port, `\\\\files.example.com@445\\zylon-samba`).

```
\\\\files.example.com\\zylon-samba

```

5. Check **Connect using different credentials**, then click **Finish**.
6. When prompted, enter your Samba **Username** and **Password**, then click **OK**.
7. If the connection succeeds, the new mapped drive (e.g., `Z:`) will appear under **This PC**, and you can browse its contents.

***

### 2. Configure Zylon to Use Samba

With the values we have acquired in previous steps we will edit Zylon config file located in `/etc/zylon/zylon-conf.yaml`

Add the following snippet to the bottom of the file

```yaml theme={null}
integration:
  filesystem:
    enabled: true
    protocol: "samba"
    
    
external:
  samba:
    host: "YOUR_HOST_OR_IP"   # e.g. "files.example.com" or "192.168.1.50"
    port: 445                 # Swap your port if not configured has default
    name: "ROOT_PATH"
```

* **host** → The hostname or IP address where your Samba server is reachable.
* **protocol** → Must be set to `"samba"`.
* **root** → Name of the shared folder (e.g. `"Data"`).

Save and close `zylon-conf.yaml`.

***

### 3. Update Zylon to Apply Changes

Finally, execute the following command to reset Zylon and update the config

```bash theme={null}
zylon-cli sync
```

You are all set 🎉

***

### 4. Network Access Considerations (On-Premise)

Since this deployment is on-premise, ensure that the Ubuntu Server where Zylon is hosted can reach the Samba server. You do **not** need to expose SMB to the public internet—everything remains within your private network.

1. **DNS / Hosts Configuration**

* Verify that client machines can resolve the Samba host name (e.g., `files.internal.company`).
* If DNS is unavailable or inconsistent, update `/etc/hosts` (Linux/macOS) or `C:\Windows\System32\drivers\etc\hosts` (Windows) to map the hostname to its IP.

2. **Firewall & Port Access**

* Ensure that **TCP port 445** (or your custom SMB port) is open between client workstations and the Samba server.
* On the Samba server, confirm the OS firewall (iptables, firewalld, Windows Firewall, etc.) allows inbound connections on that port.
* If remote users connect via VPN, make sure the VPN subnet can route to the Samba host’s IP:445.

***

### 5. Credentials

When a user enables Samba integration for the first time via the Zylon front end, they will be prompted to enter:

* **Username**
* **Password**

Zylon verifies these credentials immediately. If they are invalid, the front end displays an error message, and the user must re-enter correct credentials. Once valid, Zylon securely stores the credentials for subsequent access to the share; no manual environment-variable setup is required.

> Note: Credentials are scoped per user account. If multiple users need to connect to the same share, each must enter valid credentials with appropriate access.---

### 6. Troubleshooting

### 6.1 “Cannot resolve host” or “Name or service not known”

* **DNS/Hosts:** Verify that the Samba hostname can be resolved:

  ```bash theme={null}
  ping files.internal.company
  ```

* If DNS fails, update each client’s hosts file with:

  ```
  192.168.1.50   files.internal.company
  ```

### 6.2 “Cannot connect to host”

* **Port Reachability:**

  ```bash theme={null}
  nc -vz files.internal.company 445
  ```

(or replace `445` with your custom port).

* If test fails, confirm firewall rules on both the client network segment and the Samba server.

### 6.3 Authentication Failed / Wrong Credentials

* If a user enters incorrect Samba credentials in the Zylon front end, they will see an immediate error like “Authentication failed: invalid username or password.”
* To correct, the user should re-enter their valid Samba username and password via the integration UI.
* On the Samba server side, verify that the account exists and has permissions in `/etc/samba/smb.conf`:

  ```bash theme={null}
  sudo smbpasswd -a yourUser
  testparm -s
  sudo tail -f /var/log/samba/log.smbd
  ```

### 6.4 “Invalid protocol version”

* Ensure your server and Zylon both support **SMB2 or higher**.
* To force SMB2+ on the server, add under `[global]` in `/etc/samba/smb.conf`:

  ```
  server min protocol = SMB2
  ```

Then restart Samba:

```bash theme={null}
sudo systemctl restart smbd
```

* If you must use SMB1, contact the Zylon team for a custom client build.

***

### 8. Additional Notes

* **Only Samba (SMB) Is Supported for File System Integrations**

At this time, Zylon’s integration framework supports **only SMB2+ file system mounts**. If you require a different protocol (e.g., NFS, FTP, WebDAV), contact the Zylon team.

* **SMB1 Support**

SMB1 is deprecated and insecure. If your environment still requires SMB1, reach out to us. We can provide guidance or build a compatible client.

* **Performance Tips**
  * For large repositories, ensure your Samba server has sufficient I/O and network bandwidth.
  * On Linux, mounting with `cache=none` can reduce stale‐file issues if users frequently modify files outside Zylon.

You are now ready to integrate Zylon with your Samba file system. Once connected, users will be able to browse and manage shared files directly from the Zylon interface.