# EC2 Files

**EC2 → Files** browses the file system of an instance and opens text files, over AWS Systems Manager Session Manager. You do not need SSH, an open port, the AWS CLI or the Session Manager plugin. It is meant for the moments when you need to read a config or a log on a host, or fix one line in a config, without opening a terminal and remembering paths.

Files are read only until you turn writes on. Every save shows its diff, asks again, and keeps a backup of the old file on the instance.

## Open files

1. Open **EC2**, choose the profile and region, select an instance and open the **Files** tab.
2. Click **Open files**.

Nothing connects until you click. Opening starts one Session Manager session on the instance, which AWS logs in CloudTrail like any session start, and which your account may record, including file contents. The button is disabled, with the reason, when the instance is not running ("Session Manager needs a running instance; this one is stopped.") or your role may not start sessions.

**Open files** reopens the last file you had open on that instance. If it is gone, the home folder opens with a short note ("app.conf is gone.").

### What the instance needs

- A Linux instance with `/bin/sh`, online in Systems Manager (SSM Agent running, an instance profile that allows Systems Manager).
- GNU `find`, `stat`, `base64`, `sha256sum`, `sha1sum` and `timeout`, as on Amazon Linux, Ubuntu, Debian and RHEL. BusyBox and macOS instances are not supported.

### Who the operations run as

Files runs as **root** when passwordless `sudo` works for the session user (`sudo -n`), and as the session user (usually the SSM user) otherwise. The header shows which (see below), and so do the writes dialog and every save confirmation.

ARNscope turns off shell history and echo in the Files session, so its commands do not stay in the instance's shell history. If that is not possible, a warning says so.

## The header

| Item | Meaning |
| --- | --- |
| **Files · name** | The instance's Name tag (or its ID). Click to copy it; right-click to copy the current path, the instance ID or the Name. |
| Identity chip, for example **Root · i-0abc1234…** | Who the operations run as, on which instance. It turns red while writes are on. Hover for the full identity: "Operations run as root on i-0abc… (web-1) with profile prod, account 123456789012." |
| **Prod** | ARNscope thinks this is production: the profile name contains `prod`, `production` or `prd` as a word, or the instance has an `Environment`, `Env` or `Stage` tag set to `prod` or `production`. Production gets an extra confirmation on every save. |
| **Allow writes** | The writes switch. Off shows **Writes off**; on shows a red **Writes on · N min** with the minutes left. |
| **End session** | Closes the Session Manager session. Unsaved changes are kept (see [Unsaved changes](#unsaved-changes)). |

## Browse

- **Path on instance**: type or paste a path and press Enter. `~` is the session user's home, and a relative path is relative to the folder on screen. A folder opens in the list; a file opens in the viewer and its folder is listed. **Cmd+L** focuses the path bar.
- **Pinned folders**: `/etc`, `/var/log` and `~`. On an instance whose Name or tags mention StarRocks, also `/etc/starrocks` and `/var/log/starrocks`.
- The breadcrumb above the list goes to any parent folder.
- **Filter names** narrows the folder. Sort by **Name**, **Size** or **Modified**; folders stay first.
- Double-click a file or folder, or select it and press Enter. **Backspace** goes up a folder. From the path bar, the down arrow moves into the list.
- A folder lists at most 5,000 entries ("Showing first 5,000. Type in the filter or path bar to narrow.").

Some rows are dimmed and do not open, with the reason on hover: a file or folder the session user cannot read (with its owner, group and mode, for example `root:root 0640`), a broken symbolic link, a device, socket or FIFO, or a name that is not valid UTF-8 ("open it in Shell").

## Read a file

The viewer shows the file name, its folder, owner, group, mode and size, and the link target when you opened a symbolic link. Toolbar: **Save**, **Restore backup**, **Wrap long lines**, **Reload from the instance** and **Copy path**.

| File | What happens |
| --- | --- |
| UTF-8 text up to 1 MiB | Opens, and can be edited with writes on. |
| Text from 1 to 5 MiB | Opens read only ("Larger than 1 MiB: read-only."). |
| Larger than 5 MiB | Not read in full, since that would be slow over Session Manager. **View first 256 KB** shows the start, read only. |
| Binary (a NUL byte in the first 8 KB) | Not shown. The viewer suggests `hexdump -C <path> \| less` in Shell. |
| Mixed line endings, or old-style CR line breaks | Read only; edit it in Shell. |
| Windows (CRLF) line endings, or a UTF-8 BOM | Opens and edits normally; a chip says "CRLF (kept on save)" or "UTF-8 BOM (kept on save)". |

If the file appears in the instance's cloud-init user data, a warning stays above it: "Appears in this instance's user data (Terraform). Host edits are lost when the instance is replaced." Change it in your Terraform or launch template too.

### Find in a file

Click in the file and press **Cmd+F**. The find bar has **Match case** (Aa), **Whole word** (W) and **Regular expression** (.*), and shows "3 of 12". Enter goes to the next match, Shift+Enter to the previous one, Esc closes it. Find works in read-only files too.

## Read only by default

A Files session starts with writes off. An editable file shows "Read-only. Turn on Writes to edit." with a **Turn on Writes** button. Pressing Cmd+S with writes off points you at that button instead of saving.

### Turning on writes

Use **Allow writes** in the header or **Turn on Writes** above the file. ARNscope first checks who the session runs as, then shows a native dialog, **Turn on writes?** (**Turn on writes on production?** for a production instance). The page itself cannot answer it. It names:

- the instance ID and Name, with "PRODUCTION" in front when it looks like production,
- the user saves run as,
- the profile, account and region,
- and what follows: each save shows a diff and asks again, keeps a backup on the instance (the last 10 per file), and is recorded in the local activity log without its content.

Click **Turn on writes** to continue, or **Cancel** to stay read only.

### When writes turn off again

- **After 15 minutes without a save.** Each successful save restarts the 15 minutes; reading and browsing do not. The editor goes read only and says "Writes turned off after 15 minutes. Turn on again to save." Your changes are kept.
- **When the session is reopened.** An idle Files session closes after 10 minutes without an operation, and ARNscope reopens it on your next action; writes are off after that. The same happens after **Reconnect**.
- **When you turn them off**, or end the session.

## Edit and save

1. With writes on, edit the file. The viewer shows **Unsaved** and the bar says "Editable · saves as root on web-1".
2. Press **Cmd+S** (or **Save**). If nothing changed: "No changes to save."
3. **Review the diff.** The file on the instance ("On the instance") against your changes ("Your changes"), line by line.
4. **Confirm.** A red bar reads, for example, "Save /etc/app/app.conf on PRODUCTION web-1 as root (1.2 KB). A backup is kept first." Click **Save** (or press Cmd+Enter), or **Cancel** (Esc) to go back to editing.
5. **Production only:** a second native dialog, **Save to production?**, names the path, the instance ID and Name, the profile, the user, the account and region. Click **Save to production**, or **Cancel** ("Save cancelled. Your changes are kept.").

When it is saved: "Saved. Backup: /var/lib/arnscope/backups/… The instance keeps the last 10 backups. Restore backup is in the toolbar. The service may need a restart to apply it." ARNscope does not restart anything; do that in Shell if the service needs it.

### How a save works on the instance

- **It refuses a stale save.** ARNscope remembers the exact version you opened. If the file changed on the instance since, nothing is written and the viewer says "This file changed on the instance since you opened it." with **Show their changes** (a diff of the instance's version against yours) and **Reload and discard mine**.
- **It keeps owner, mode and SELinux context.** The new content is written to a temporary file in the same folder, checked against a checksum, given the old file's owner and mode (and SELinux context where SELinux is on), and only then put in place of the file.
- **It backs up first.** The current file is copied to the backup folder before it is replaced. If the backup cannot be made, the save stops and nothing changes.
- **It needs room.** A save stops before writing if the disk does not have about twice the file's size plus 1 MiB free.
- It refuses a path that is a symbolic link (it saves the file the link points to, which is what the viewer opened) and a file with more than one hard link ("Edit it in Shell").
- If the session drops mid-save, the viewer says "The save may or may not have happened. Reload to check. Your changes are kept." **Reload** checks and tells you which.

Every save attempt is recorded in the local activity log with its path, size and outcome, never the content.

### Backups on the instance

| Files runs as | Backup folder |
| --- | --- |
| root | `/var/lib/arnscope/backups` (readable by root only) |
| the session user | `~/.arnscope/backups` |

ARNscope keeps the newest 10 backups of each file and deletes older ones when it saves. Backups stay on the instance; nothing is copied to your Mac. **Copy path** gives the backup's full path.

## Restore backup

1. Open the file and click **Restore backup** (the clock icon). It is disabled while you have unsaved changes: save or discard them first.
2. The list shows "Backups of app.conf, newest first. The instance keeps the last 10." with each backup's save time (local) and size, and **Copy path**.
3. Pick one. The diff shows the file on the instance against "This backup".
4. Click **Restore this backup** (writes must be on), then confirm. The bar reads "Restore … A backup is kept first. Restores the backup from Nov 9, 17:56." Production asks again in the native dialog.

A restore is a save: the current file is backed up first, so you can undo a restore the same way. A backup that is not UTF-8 text under 5 MiB cannot be restored here ("Restore it in Shell.").

## Unsaved changes

- Your edits are kept in ARNscope's memory while it runs, per instance and file, when you open another file, switch instances, end the session or lose it. They are not written to disk, so quitting ARNscope drops them.
- The **Files** tab shows a dot while an instance has unsaved changes, and the start screen says "You have unsaved changes to … on this instance. Open files to continue."
- Opening another file with unsaved changes asks: "Unsaved changes in app.conf. Review and save, Discard, or Cancel." **Reload from the instance** asks "Discard your changes and reload from the instance?".
- If the file changed on the instance while your draft waited, you get the stale-save notice instead of overwriting it.

## Session limits and lost sessions

- ARNscope keeps at most 4 Files sessions open at once ("Close a Files tab first."), separate from the Shell tab's 8 shell sessions.
- An idle Files session closes after 10 minutes and reopens on your next action (with writes off). After an hour unused, ARNscope forgets it ("The Files session has ended.").
- When a session drops or ends, a red bar keeps what is on screen and offers **Reconnect**.

## The built-in shell

For anything Files does not do (restarting a service, a binary file, a file with mixed line endings), use the **Shell** tab on the same instance, or **Open shell** in the instance header. **Start session** opens a Session Manager shell as the instance's SSM user, inside ARNscope; **End session** closes it. Like Files, it starts only when you click, and AWS logs every session start in CloudTrail. ARNscope runs at most 8 shell sessions at once. The arrow next to **Open shell** also offers **Open in your terminal** and **Copy SSM command**.

## Opened from StarRocks

On the [StarRocks](https://arnscope.com/docs/starrocks) Logs tab, **Open in Files** opens the same log file here, on the node's instance. The session still starts only when you click **Open files** (or right away if a Files session is already open).

## Permissions

Session Manager uses your AWS identity, so there are no SSH keys or passwords to manage; access is controlled by IAM. These are the actions ARNscope uses:

| What | Actions |
| --- | --- |
| Open Files (and reopen it) | `ssm:StartSession`, `ssm:TerminateSession`; `ec2:DescribeInstances` for the instance's Name, account and tags (best effort) |
| End a Files session | `ssm:TerminateSession` |
| Shell tab | `ssm:StartSession`, `ssm:TerminateSession` |

Browsing, reading, saving and backups travel over the open session and need no further AWS actions. What a save may change is decided on the instance: by file permissions, and by whether the session user has passwordless `sudo`. The instance needs an instance profile that allows Systems Manager. The [IAM permission check](https://arnscope.com/docs/iam-permission-check) shows which of these your role has.

## Limitations

- Linux instances with GNU tools only; no Windows, BusyBox or macOS instances.
- Text files only. Edits up to 1 MiB, reading up to 5 MiB (the first 256 KB beyond that). Files with mixed line endings or old-style CR breaks are read only.
- No creating, renaming, deleting, uploading or downloading files, and no changing owners or modes. Use Shell for those.
- Saves cannot restart services.
- Folders list at most 5,000 entries.
- Root access only through passwordless `sudo`; no other way to switch user.
- At most 4 Files sessions at once.
- Unsaved changes live in memory and are lost when ARNscope quits.
- The production check is a heuristic on the profile name and tags; the dialogs always show the real instance, profile and account.

Need another mode? Write to [hello@arnscope.com](mailto:hello@arnscope.com) and tell us what you use.

Source: https://arnscope.com/docs/ec2-files
