명령어로 서버 관리하기

스페이스빌더 실행 파일(setfn-spacebuilder)에는 서버 시작 기능 외에 터미널용 관리 명령이 들어 있습니다. 관리자 페이지에 로그인할 수 없을 때 계정과 접속 제한을 복구하거나, 포트와 언어 같은 설정을 확인할 때 사용합니다.

이 문서는 서버를 설치하고 운영하는 관리자를 위한 문서입니다. 일반적인 관리는 관리자 페이지에서 하고, 관리자 페이지를 사용할 수 없을 때만 명령어를 사용하세요.

시작하기 전에

• 스페이스빌더가 설치된 컴퓨터의 터미널에서 실행합니다.
• 스페이스빌더를 실행하는 운영체제 사용자 계정으로 실행합니다. 기본 설정 경로는 그 사용자의 홈 폴더 아래에 있으며, 별도 경로를 사용한다면 운영 중인 서버와 같은 설정 파일을 지정해야 합니다.
• 예시는 실행 파일이 홈 폴더(~/setfn-spacebuilder)에 있는 경우입니다. 다른 위치에 두었다면 해당 경로로 바꿔 입력합니다.
• user, unblock, ip, admin, login, logout으로 시작하는 관리 명령은 서버를 멈춘 상태에서 실행합니다.

운영 중인 서버의 설정 경로 지정하기

Linux의 기본 설정 파일은 ~/.config/SetFN/config.yaml입니다. 서비스를 다른 계정이나 별도 설정 경로로 실행한다면 서비스 실행 명령에 지정된 경로를 확인합니다.

-c 또는 --config로 그 설정 파일을 지정합니다. 다음은 /srv/setfn/config.yaml로 운영하는 서버의 예시입니다. 실제 파일 경로로 바꿔 입력합니다.

~/setfn-spacebuilder -c /srv/setfn/config.yaml port get
~/setfn-spacebuilder -c /srv/setfn/config.yaml user list

이 문서의 다른 관리 명령에도 같은 -c 옵션을 붙입니다. 서버를 -H 또는 --home으로 경로를 지정해 운영한다면 그 옵션도 똑같이 붙입니다. -c와 함께 지정하면 설정 파일은 -c로 지정한 파일을 사용합니다.

서버를 멈추고 다시 켜기

사용자·접속 제한·기기 연결을 관리하는 명령과 admin status·admin logout-all 등은 서버의 데이터베이스를 직접 엽니다. 다른 프로세스가 같은 데이터베이스를 사용 중이면 재시도 후 Database is still locked 메시지로 끝날 수 있습니다. admin reset-config는 데이터베이스를 열지 않고 설정 파일을 삭제하지만, 이 작업도 서버를 멈춘 뒤 수행합니다.

자동 시작을 설정했다면 먼저 서버를 멈춥니다.

sudo systemctl stop setfn-spacebuilder

필요한 명령을 실행한 뒤 서버를 다시 켭니다.

sudo systemctl start setfn-spacebuilder

터미널에서 직접 실행 중이라면 그 터미널에서 Ctrl+C를 눌러 멈춥니다.

콘솔 접근 비밀번호 정하기

user와 unblock 명령은 실행할 때 Console Access Password를 묻습니다. 이 비밀번호는 환경 변수 SETFN_CONSOLE_PASSWORD에 정한 값입니다. 명령을 실행하기 전에 같은 터미널에서 값을 정합니다.

export SETFN_CONSOLE_PASSWORD="직접 정한 비밀번호"

이 값은 로컬 콘솔 명령의 접근을 확인하는 데만 씁니다. 워크스페이스 관리자 비밀번호나 SetFN 계정 비밀번호와는 관계가 없습니다. Console Access Password에는 이 터미널에서 지정한 값을 입력합니다.

명령 한눈에 보기

각 명령의 자세한 옵션은 명령 뒤에 --help를 붙여 확인합니다.

~/setfn-spacebuilder user --help

로그인할 수 없을 때 복구하기

아래 명령은 모두 서버를 멈추고 콘솔 접근 비밀번호를 정한 뒤 실행합니다.

로그인 차단 풀기

로그인 실패가 반복되어 관리자 접속이 차단되었다면 접속할 컴퓨터의 IP를 보안 화이트리스트에 추가합니다.

~/setfn-spacebuilder unblock --ip 203.0.113.10

현재 복구 상태는 다음 명령으로 확인합니다.

~/setfn-spacebuilder unblock --status

IP를 추가해도 접속할 수 없다면 로그인 보안 기능을 잠시 끕니다.

~/setfn-spacebuilder unblock --all

~/setfn-spacebuilder unblock --enable-security

대상 사용자 계정 확인하기

비밀번호와 역할을 바꾸려면 워크스페이스에 등록된 계정의 로그인 사용자 이름이 필요합니다. 다음 명령으로 사용자 목록을 확인합니다.

~/setfn-spacebuilder user list

아래 예시의 <사용자 계정>을 꺾쇠괄호까지 포함해 목록의 Username 열에 있는 로그인 사용자 이름으로 바꿉니다. Nick 열은 화면에 표시되는 이름입니다.

관리자 비밀번호 바꾸기

~/setfn-spacebuilder user password -u "<사용자 계정>" --password "새 비밀번호"

입력한 명령은 터미널 기록에 남으므로, 로그인한 뒤 관리자 페이지에서 비밀번호를 한 번 더 바꾸는 것을 권장합니다. 새 비밀번호는 서버의 비밀번호 규칙을 따르며, 흔히 쓰이거나 유출된 비밀번호는 거절됩니다. 새로 설치한 서버의 기본 규칙은 12자 이상입니다.

관리자 2단계 인증 끄기

관리자가 인증 앱과 복구 코드를 모두 잃어 로그인할 수 없고, 관리자 페이지에서 초기화해 줄 다른 최고관리자도 없을 때 사용합니다.

~/setfn-spacebuilder user mfa reset "<사용자 계정>"

그 계정의 인증 앱 등록과 복구 코드가 지워지고 로그인 중이던 세션이 모두 끝납니다. 다음 로그인은 비밀번호만으로 하며, 관리자 2단계 인증 필수 정책이 켜져 있으면 로그인 뒤 다시 등록해야 합니다. 실행 기록은 감사 로그에 2단계 인증 초기화로 남습니다. 2단계 인증을 쓰지 않는 계정에 실행하면 바뀌는 것 없이 안내만 표시됩니다. 등록 절차는 관리자 2단계 인증 설정하기를 참고합니다.

관리자 권한 되찾기

관리자 권한이 있는 계정이 없다면 기존 사용자의 역할을 바꿉니다.

~/setfn-spacebuilder user promote -u "<사용자 계정>" -r admin

-r admin의 admin은 부여할 역할 값이며, admin status처럼 명령 이름에 쓰는 admin과는 다릅니다.

사용자 계정 추가하고 삭제하기

~/setfn-spacebuilder user add -u newadmin -n "새 관리자" --admin

계정을 삭제할 때는 사용자 이름을 지정합니다. 마지막 관리자는 삭제할 수 없습니다.

~/setfn-spacebuilder user delete -u olduser

IP 접근 제한 관리하기

IP 접근 제한을 켜면 허용 목록에 있는 IP에서만 관리자 페이지에 접속할 수 있습니다. 허용 목록을 잘못 설정해 관리자 페이지에 접속할 수 없을 때 명령어로 고칩니다.

현재 상태와 허용 목록을 확인합니다.

~/setfn-spacebuilder ip status

허용 목록에 IP 주소나 CIDR 범위를 추가하거나 제거합니다.

~/setfn-spacebuilder ip add --ip 192.168.1.100
~/setfn-spacebuilder ip add --ip 192.168.1.0/24
~/setfn-spacebuilder ip remove --ip 192.168.1.100

접근 제한을 켜거나 끕니다.

~/setfn-spacebuilder ip enable
~/setfn-spacebuilder ip disable

서버 설정 확인하기

~/setfn-spacebuilder port get
~/setfn-spacebuilder homepath get
~/setfn-spacebuilder lang get

• 터미널 메시지 언어는 lang set ko처럼 바로 바꿀 수 있습니다.
• port set <포트>와 homepath set <경로>는 값을 바꾸지 않고 설정 파일에 입력할 내용만 보여 줍니다. port set은 해당 포트를 사용할 수 있는지도 표시합니다. 설정 파일을 고친 뒤 서버를 다시 시작해야 적용됩니다.
• 포트는 3000부터 65535까지 사용할 수 있습니다. 기본 포트는 8510입니다.

SetFN 계정의 기기 연결 복구하기

이 명령은 SetFN 계정과 서버 기기의 연결을 관리합니다. 워크스페이스 사용자 계정의 로그인 차단이나 비밀번호는 앞의 user·unblock 명령으로 복구합니다.

서버를 멈추고 운영 중인 서버와 같은 설정 경로를 사용해 연결을 시작합니다.

~/setfn-spacebuilder login

터미널에 표시된 안내에 따라 브라우저에서 승인을 완료합니다. 이미 등록된 기기를 다시 연결하려면 다음 명령을 사용합니다.

~/setfn-spacebuilder login --force

인증 정보가 만료되었거나 유효하지 않으면 기존 연결을 해제한 뒤 다시 등록합니다.

~/setfn-spacebuilder logout
~/setfn-spacebuilder login --force

logout은 기본적으로 로컬 사이트 토큰, 기기 키, 인증 파일을 모두 정리합니다. logout --unlink도 같은 동작을 하는 호환용 옵션입니다. 기기 키와 인증 파일은 유지하고 사이트 세션 토큰만 정리하려면 logout --keep-link를 사용합니다.

재연결이 끝나면 서버를 다시 시작하고 관리자 페이지에서 라이선스 등록 상태를 확인합니다.

서버 상태와 로그인 세션 관리하기

서버 상태와 현재 설정을 확인합니다.

~/setfn-spacebuilder admin status

계정 정보 유출이 의심되면 모든 사용자를 로그아웃시킵니다. 사용자는 다시 로그인해야 합니다.

~/setfn-spacebuilder admin logout-all

지식 저장소의 백업과 복원은 지식 저장소 운영하기를 참고하세요.

알아두기

• Linux는 프로세스 이름을 15자까지만 보관하므로 ps -e나 top에는 setfn-spacebuil로 표시됩니다. 실행 중인지 확인할 때는 pgrep -f setfn-spacebuilder를 사용합니다.
• 계정과 차단 관련 명령은 서버를 멈춰야 실행할 수 있습니다. 사용자 추가나 차단 관리는 가능하면 관리자 페이지에서 하세요.

관련 문서

• Linux에 설치하기
• 차단 관리
• 관리자 2단계 인증 설정하기
• 지식 저장소 운영하기
• 문제 해결 가이드