Change File Permissions

Change Unix file permissions (chmod) for files and directories

Endpoint

POST /api/servers/:server/files/chmod

Authentication

Requires Bearer token authentication via the Authorization header.

Path Parameters

server · string · required

The UUID of the server

Request Body

root · string · required

The root directory for chmod operations (all paths are relative to this)

files · array · required

Array of file chmod operations

Show File Object

file · string · required

File or directory path (relative to root)

mode · string · required

Unix file mode in octal notation (e.g., “0755”, “0644”)

Response

Returns 204 No Content on success.

Example Request

cURL - Single File

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/chmod" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "root": "/",
    "files": [
      {"file": "start.sh", "mode": "0755"}
    ]
  }'

curl -X POST "https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/chmod" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "root": "/scripts",
    "files": [
      {"file": "backup.sh", "mode": "0755"},
      {"file": "config.yml", "mode": "0644"},
      {"file": "data/", "mode": "0755"}
    ]
  }'

await fetch(
  'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/chmod',
  {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_TOKEN',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      root: '/',
      files: [
        { file: 'start.sh', mode: '0755' },
        { file: 'stop.sh', mode: '0755' }
      ]
    })
  }
);

import requests

requests.post(
    'https://wings.example.com/api/servers/d3aac109-f0fc-4674-b5bc-199bb50e6b88/files/chmod',
    headers={'Authorization': 'Bearer YOUR_TOKEN'},
    json={
        'root': '/',
        'files': [
            {'file': 'run.sh', 'mode': '0755'},
            {'file': 'config/', 'mode': '0755'}
        ]
    }
)

Common Permission Modes

Mode	Permission	Description
0644	-rw-r--r--	Standard file (owner read/write, others read)
0755	-rwxr-xr-x	Executable file or directory (owner all, others read/execute)
0600	-rw-------	Private file (owner read/write only)
0700	-rwx------	Private executable or directory (owner only)
0777	-rwxrwxrwx	Fully accessible (not recommended)

Behavior

• Operations are performed concurrently for better performance
• Both files and directories can have permissions changed
• Mode must be a valid octal string (e.g., “0755”, “0644”)
• Directories are not processed recursively - only the specified path is modified
• Symlinks have their target’s permissions modified
• Path traversal is prevented

For shell scripts and other executables, use mode 0755 to make them executable. For configuration files, use 0644.

Error Responses

400 Bad Request

Invalid mode format (must be octal string like “0755”)

401 Unauthorized

Missing or invalid Bearer token

404 Not Found

Server or file does not exist

500 Internal Server Error

Failed to change permissions (permission denied, etc.)

Use Cases

• Make shell scripts executable
• Secure configuration files
• Fix permission issues preventing server startup
• Set proper permissions after file upload
• Prepare files for execution

Source Reference

Implementation: router/router_server_files.go (postServerChmodFile function)