linux timeout command examples: 리눅스 작업 시간 제한

리눅스에서 오래 걸리는 작업을 안전하게 끊으려면 timeout 명령으로 실행 시간 상한을 두는 방식이 가장 단순해요. 기본 동작은 지정한 시간이 지나면 TERM 신호를 보내는 것이고, 정리 시간이 더 필요하면 -k로 강제 종료 시점을 따로 둘 수 있어요. 아래에서는 linux timeout command examples를 기준으로 문법, 옵션 비교, 상황별 선택 방법을 정리해요.

한눈에 보기

timeout은 지정한 시간 안에 끝나지 않은 명령에 신호를 보내는 GNU Coreutils 계열 도구예요. 배포 스크립트, 외부 API 호출, 로그 압축, 오래 걸리는 조회 작업처럼 끝나지 않을 가능성이 있는 명령을 감쌀 때 유용해요.

기본 형태는 timeout DURATION COMMAND예요.
DURATION에는 숫자와 선택 접미사를 넣고, 접미사를 생략하면 초로 해석해요.
기본 신호는 TERM이며, -s 또는 --signal로 바꿀 수 있어요.
첫 신호 후에도 끝나지 않을 때를 대비하려면 -k를 사용해요.
시간 초과 시 기본 종료 코드는 124예요.
명령 자체의 종료 상태를 유지하려면 --preserve-status를 붙여요.

기본 문법과 시간 지정 방식

기본 문법은 timeout [옵션] DURATION COMMAND [인자...] 형태예요. DURATION은 명령을 얼마나 기다릴지 정하는 값이고, COMMAND는 실제로 실행할 외부 명령이에요. 예를 들어 외부 요청을 보내는 스크립트라면 timeout DURATION curl https://example.com처럼 감쌀 수 있어요.

DURATION에는 s, m, h, d 같은 접미사를 붙일 수 있어요. 접미사를 생략하면 초 단위로 계산돼요. 소수점을 사용하는 형식도 지원하지만, 운영 스크립트에서는 읽기 쉽고 의도가 분명한 값을 쓰는 편이 좋아요.

COMMAND 뒤에 오는 인자는 그대로 명령에 전달돼요. 셸 내장 명령을 직접 실행해야 한다면 bash -c '명령'처럼 셸을 통해 감싸세요. 공백이나 특수 문자가 포함된 인자는 따옴표로 묶어 셸이 먼저 해석하지 않도록 해야 해요.

자주 쓰는 옵션 비교

옵션	역할	예시
`-s SIGNAL`	시간 초과 시 보낼 신호를 지정해요	`timeout -s TERM DURATION COMMAND`
`--signal=SIGNAL`	신호 지정을 긴 옵션 형태로 써요	`timeout --signal=TERM DURATION COMMAND`
`-k GRACE`	첫 신호 후 추가 대기하고, 그 뒤 KILL을 보내요	`timeout -k GRACE DURATION COMMAND`
`--preserve-status`	시간 초과여도 명령의 종료 상태를 유지해요	`timeout --preserve-status DURATION COMMAND`
`--foreground`	터미널 제어가 필요한 명령을 위해 포그라운드에서 실행해요	`timeout --foreground DURATION COMMAND`
`--verbose`	timeout 자체의 진단 메시지를 stderr로 보내요	`timeout --verbose DURATION COMMAND`

표의 DURATION, GRACE, COMMAND는 실제 값으로 바꿔 사용하는 자리표시자예요. 특히 -k는 첫 신호를 보낸 뒤에도 프로세스가 남아 있을 때만 의미가 있어요. 무조건 KILL을 먼저 보내고 싶다면 -s KILL을 사용할 수 있지만, 정리 작업을 할 기회가 사라진다는 점을 고려해야 해요.

단계별 사용 방법

제한 시간을 정해요. 외부 API 호출, 배포 스크립트의 대기 작업, 오래 걸리는 압축처럼 끝나지 않을 수 있는 작업에 상한을 둡니다.
기본형으로 명령을 감싸요. timeout DURATION COMMAND 형태로 실행하고, 먼저 TERM 신호가 제대로 동작하는지 확인해요.
정리 시간이 필요하면 -k를 붙여요. timeout -k GRACE DURATION COMMAND처럼 첫 신호와 강제 종료 사이의 여유를 둘 수 있어요.
신호를 바꿔야 하면 -s를 사용해요. 정상 종료 절차를 유도하려면 TERM을, 즉시 중단이 필요하면 KILL을 검토해요.
종료 코드를 확인해요. 스크립트에서는 echo $?로 결과를 확인하고, 시간 초과 여부를 분기할 수 있어요.
로그를 남겨요. --verbose를 사용하면 timeout이 어떤 판단을 했는지 stderr에서 확인할 수 있어요.

시간 초과 시 기본 종료 코드는 124예요. 따라서 배포 스크립트에서는 이 값을 별도로 처리해 “작업이 끝나지 않아 중단됨”과 “명령이 실패함”을 구분하는 편이 좋아요. 다만 명령 자체가 같은 종료 코드를 반환할 수도 있으므로, 로그 메시지와 함께 판단해야 해요.

상황별 선택 기준

외부 API 호출이나 다운로드처럼 네트워크 지연이 걱정되는 작업에는 기본 TERM과 -k를 조합하는 방식이 잘 맞아요. 먼저 정상 종료를 요청하고, 일정 시간 안에 끝나지 않으면 KILL로 확실히 정리하는 흐름이에요.

로그 압축이나 임시 파일 정리처럼 종료 전에 해야 할 일이 있는 작업은 TERM만 보내는 편이 안전해요. KILL은 프로세스가 정리 작업을 수행할 기회를 주지 않기 때문이에요. 정리 시간이 길다면 -k의 대기 값을 작업 특성에 맞게 조정하세요.

터미널 입력을 받거나 TTY 신호를 기대하는 대화형 명령에는 --foreground를 검토할 수 있어요. 반대로 서비스 관리자나 컨테이너 런타임이 이미 종료 제한을 걸고 있다면 timeout과 중복되지 않는지 확인해야 해요. 두 장치가 동시에 신호를 보내면 어느 쪽이 먼저 종료를 유발했는지 로그로 구분하기 어려울 수 있어요.

주의할 점

timeout은 명령이 만든 모든 자식 프로세스까지 자동으로 완벽히 정리한다고 가정하면 안 돼요. 명령이 별도 프로세스 그룹이나 서비스 관리자 아래에서 동작한다면, 종료 범위와 신호 전달 방식을 함께 확인해야 해요.

KILL 신호는 프로세스가 무시할 수 없지만, 그만큼 정상 종료 절차를 보장하지 않아요. 데이터를 쓰는 작업이라면 TERM을 먼저 보내고 -k로 최후의 수단을 두는 구성이 일반적이에요.

--preserve-status는 시간 초과 시에도 명령의 종료 상태를 유지해요. 스크립트에서 시간 초과를 별도로 감지해야 한다면 이 옵션을 무심코 붙이지 말고, 종료 코드 해석 규칙을 먼저 정해야 해요.

배포판이나 환경에 따라 timeout의 옵션 지원 범위가 다를 수 있어요. 운영 서버에서 사용하기 전에 timeout --help와 매뉴얼을 확인하고, 컨테이너 이미지처럼 도구 구성이 다른 환경에서는 별도로 검증하세요.

자주 묻는 질문

timeout은 기본적으로 어떤 신호를 보내나요?

기본은 TERM 신호예요. 프로세스가 정상 종료 절차를 밟게 하려면 기본값을 그대로 두고, 즉시 중단이 필요하면 -s KILL처럼 신호를 바꿔요.

`-k`는 언제 쓰나요?

-k는 첫 신호 후에도 프로세스가 끝나지 않을 때 추가로 KILL을 보내는 용도예요. 정리 작업에 시간이 필요하지만 무한 대기는 막고 싶을 때 timeout -k GRACE DURATION COMMAND 형태로 사용해요.

시간 초과 종료 코드는 어떻게 확인하나요?

GNU timeout은 시간 초과 시 기본적으로 124를 반환해요. 명령 자체의 종료 상태를 유지하려면 --preserve-status를 붙이고, 스크립트에서는 $?를 확인해 분기해요.

출처

GNU Coreutils 매뉴얼의 timeout Invocation: https://www.gnu.org/software/coreutils/manual/html_node/timeout-invocation.html
man7.org의 timeout 매뉴얼: https://man7.org/linux/man-pages/man1/timeout.1.html
GNU Coreutils timeout 소개: https://www.gnu.org/software/coreutils/timeout

관련 운영 글로 리눅스 프로세스 신호와 종료 절차를 함께 읽어 보세요. timeout이 보내는 TERM과 KILL의 차이를 서비스 운영 관점에서 정리한 글이에요.